API Evolutions
This repository contains the documentation of a RESTful API offering lightweight Jira-like project management features.
It illustrates all the possible evolutions of an API according to the following listing:
Structure
The commit history is used to illustrate evolutions. In addition, the folder api-versions contains all versions of the API. One version is created per commit.
The latest version is openapi.yaml.
OpenApi enrichments
Affiliation
An x-affiliation property is introduced. It is required to determine if the data of an object or linked resource can be directly affiliated to the parent object or if is a completely different data.
This property can have two values: parent or self. Default: self.
An example of such object is given with "details" at the lines 3 to 5 of the below figure. The represented resource gives us the "id" and "title" of a project along with contextual information, that we discuss in the next subsection. Here, the "details" object is used to ease human readability. Thus, all the properties that it contains (only "title" here) belong to the project, not the "details" object itself.
With links, the case is very similar. Consider a Card resource with one analytic: its creationDate. Then, this field is moved to an Analytic resource. Hence, a link Card to Analytic is added. Yet, it is required to distinguish this link to some data describing the card from links to the operations available on the card (e.g. its deletion), from links to completely different resources such as the list of all cards.
As a result, we distinguish two kinds of affiliations:
- No affiliation (self): for inner objects and linked resources, the data that they contain do not describe the parent object; for linked operations: they are performed on another resource than the parent resource.
- Affiliation to the parent (parent): for inner objects and linked resources, the data that they contain described the parent object (as illustrated in the example earlier); for linked operations: they are performed on the resource that contains the link.
Hints
Places to find ontologies and terms: