[DRAFT] Proposed API Guidelines
Please review so and feedback can be incorporated before making official guidelines.
There are three types of APIs:
1.1 Public APIs
Public APIs are the supported APIs that apps can use.
Public API requirements:
All public APIs must have at least one test case.
All public APIs must be in a header file that is published to the build directory.
All public APIs must be fully documented using doxygen markup in the public header files
All public APIs must be used in some sample code or snippet. Ideally, the sample should be one that is compiled as part of the build, and uses no experimental APIs. For rarely used public APIs, the sample might simply be a snippet in the doxygen comments.
Public APIs cannot have source- or binary- breaking changes across IoTivity versions. (Breaking changes can be made to a new API
only until it is released for the first time.)
1.2 Experimental APIs
Experimental APIs are considered to be potential future public APIs, but there is no guarantee
of support in future releases, nor is there any guarantee that breaking changes will not occur
Experimental API requirements:
Experimental APIs must be optional to compile in. That is, there must be some way to build IoTivity in a way that does not expose any experimental APIs, so that an application can easily verify that it uses only fully-supported public APIs, and so that the IoTivity code size requirement can be minimized.
Experimental APIs must be in a header file that is published to the build directory. They can be in their own header, or in a header file that is shared with public APIs but only if surrounded by an appropriate ifdef.
Experimental APIs should be fully documented using doxygen markup in the header file
Experimental APIs should ideally be used in some sample code (separate from samples that use only public APIs) or snippet. Ideally, the sample should be one that is compiled as part of the build. For rarely used APIs, the sample might simply be a snippet in the doxygen comments. Having working samples may help others evaluate and determine how ready it is for prime time before the API
moves from experimental to public.
1.3 Internal APIs
Internal APIs are considered to be usable within IoTivity but are not intended to be used
by applications that use IoTivity.
Internal API requirements:
Internal APIs must not appear in any header file that is published to the build directory
Internal APIs should ideally be documented using doxygen markup in the private header files
Internal APIs must not be used in sample code
Internal APIs must not be used by any apps other than test code. For example, this means that sample provisioning apps must not use internal APIs.
2 Programming Languages
There may be multiple programming languages supported (whether publically or experimentally).
The API maintainer may have a separate sub-maintainer per programming language.
3 Breaking Changes
The API maintainer shall be responsible for API breaking change policy. The proposed policy is:
APIs can be deprecated by marking them as @deprecated. The associated text should explain
what an application should do instead. Public APIs must be @deprecated for at least two
releases (i.e., one year of releases) before they can be removed. The reasons for deprecation
of APIs should be discussed on the iotivity-dev list.
4 Gerrit review
All changes that affect any public API header must include the API function leader and/or appropriate
language-specific experts as code reviewers. The language-specific experts are responsible for
ensuring that the above guidelines are met, and also reviewing the doxygen documentation for
completeness and clarity.
Java: Rick Bell
All others: Dave Thaler
Implementers are encouraged to discuss the proposed APIs on the iotivity-dev list before they
are implemented, since changes are typically much more costly after the APIs are implemented.