 | This section is a work in progress. Feedback is greatly appreciated in ironing out the desired interaction model. Please post questions, comments, concerns, suggestions, etc. |
Develop a published API for JA-SIG uPortal
A published API is a well-defined contract governed by the Release Strategy. The published API will be defined through a well-defined process. The goal is to build at least two binaries for JA-SIG uPortal: uPortal-api.jar and uPortal.jar; uPortal-api.jar contains the published APIs for JA-SIG uPortal; uPortal.jar will contain the unpublished implementation APIs. (JavaDoc API documentation may still be generated for the "unpublished" APIs, but these APIs will not necessarily follow the Release Strategy.)
What do you mean, "published"?
Of course, we always try to write good APIs. And we try not to break things. But, realistically, nothing is gotten perfect initially and much code will require changes. Defining published APIs is mechanism for controlling how much of the code we need to be really careful about changing. Code depending on published uPortal APIs can expect those APIs to change only according to a careful process that evolves the APIs and balances the cost of changes with the value of those changes. Contrastingly, code that depends on random classes in uPortal that are not designated as published APIs will break more frequently with more frequent, less careful changes to improve uPortal's implementation.
Process for Defining Published APIs
To propose a new published API, please follow these steps:
- identify an extension point for the JA-SIG uPortal code-base;
- refactor, if necessary, the JA-SIG uPortal code-base to isolate this extension point; and,
- raise the issue on the dev list describing the extension point and use-case(s).
If the dev list agrees to the addition of a new API, then:
- open a Jira issue to capture the issue;
- check-in the re-factored code into the published APIs distribution; and,
- check-in the re-factored code into the implementation distribution.
Process for Modifying Published APIs
The published APIs follow a more strick change model with respect to the Release Strategy than the rest of the code. However, it is expected that the published APIs will need to be changed from time to time. While this should avoided, or minimized, the process to change a published API is similar to proposing a new API:
- raise the issue on the dev list describing the extension point and use-case(s);
- identify the desired feature(s); and,
- identify the issue(s) with the current published APIs.
If there is concensus that a change to the published API is appropriate, then:
- open a Jira issue to capture the issue;
- check-in the re-factored code into the published APIs distribution; and,
- check-in the re-factored code into the implementation distribution.
The Published API Distribution
The SCM will be restructured to contain a new source directory called "source-api". All published APIs will be moved to this directory. The build will be modified to create a new JAR called uPortal-api.jar or uPortal-api-<version>.jar. The uPortal-api-<version>.jar will be used to compile the uPortal implementation JAR.
A separate project for the published APIs could also be implemented instead of a new source directory within the existing project. This choice is especially attractive in Maven-based environments which follow a one-artifact-per-project model.
Relationship to JA-SIG uPortal 3
The Release Strategy defines an upgrade path for published APIs in any major upgrade of JA-SIG uPortal. The JA-SIG uPortal 3 effort is no exception. Published APIs may not be supported in a major upgrade with binary compatibility, or schema compatibility, but some upgrade path should be defined.