Api design for c pdf

The life cycle of a typical API is then described, including pre-release, release, maintenance, completion, and deprecation. The various terms for backward and forward compatibility are defined, including functional compatibility, source compatibility, and binary compatibility. The important issue of how you can make changes to an API while still maintaining backward compatibility is discussed, including how to make API changes such as adding, changing, deprecating, and removing functionality.

Finally, the importance and implementation of API reviews are presented. Well-written documentation is a critical element of an API. It describes what an API does and how it behaves, such as defining units for parameters, error conditions, or thrown exceptions.

This chapter provides a checklist for what you should document and also details the various types of documentation that you can produce, including automated API documentation, overview documentation, code samples, tutorials, release notes, and license information.

A large part of the chapter is dedicated to the effective use of Doxygen as a way to create API documentation automatically. This chapter starts off by presenting the case for writing tests and then categorizes the various types of testing you can perform on an API, including white box testing, black box testing, and gray box testing, as well as unit testing, integration testing, and performance testing.

It then covers how to write good tests by detailing the qualities of a good test, what to test, how to focus your testing effort, and how to work effectively with a QA team. The next topic looks at how you can write code that is more amenable to testing.

This covers techniques such as test-driven development TDD , stub objects and mock objects, how to test private code, proper use of assertions, contract programming, and internationalization issues. In the final section, various automated testing tools are presented, such as a range of test harnesses, code coverage tools, bug tracking systems, and continuous build systems.

This begins by explaining why you may want to do this and the issues that you will face in doing so, such as cross-language compatibility issues. In each case, specifics are covered such as how to expose a class hierarchy, define constructors, support inheritance, use language specific features such as properties in Python, and how to achieve cross-language polymorphism.

Extensibility is an important aspect of API design as it lets users expand the base functionality without requiring you to change the API. The bulk of this chapter deals with how to create a Plugin API, i. The chapter also covers other ways to extend an API, such as through inheritance, with a specific example of the Visitor design pattern. It also describes extensibility via templates, where the concept of policy-based templates and the curiously recurring template pattern CRTP are presented.

Styles Publisher Summary 5. Performance Publisher Summary 7. Versioning Publisher Summary 8. Documentation Publisher Summary 9. Testing Publisher Summary Scripting Publisher Summary Extensibility Publisher Summary Libraries A.

Get it now. API design matters a lot. The basic approach to do this in C is to expose your API entry points directly. You just mark them as visible, decide on some naming scheme, and off you go. The client either links directly against your library, or loads the entry points manually, and calls them. This is practically how all C APIs have been designed so far. Look at sqlite, libpng, Win32, the Linux kernel - this is exactly the pattern.

In general, a direct C API has no really good way to solve this problem, as every version bump means either new entry points or more complicated loading. Often enough, you just link directly against an import library, and then you expect a shared object or DLL exporting the same symbols.

This makes it hard to dynamically use the library i. The solutions for this aim at reducing that boilerplate. Which brings us to the last topic, extensibility. How do you extend your API?