Adds API policy doc #210
Adds API policy doc #210
Conversation
tekton-robot
added
the
size/M
yes adding a new field won't break the API, removing does. |
docs/API_POLICY.md
Outdated
|
|
||
| #### Additive changes | ||
|
|
||
| - Additive changes are changes that are added to the APIs and do not cause problems for existing users of the API. |
There was a problem hiding this comment.
Additive changes are changes that are added to the APIs in a backward compatible way and thus, do not cause problems for existing users of the API.
docs/API_POLICY.md
Outdated
| #### Additive changes | ||
|
|
||
| - Additive changes are changes that are added to the APIs and do not cause problems for existing users of the API. | ||
| - If the current version of API is `/v1` then any new addition for eg. adding new field in response of a API will not affect existing users of v1 version of that API. |
There was a problem hiding this comment.
"in response" — you mean in the response of the HTTP request right ?
We should also state that adding a new field as part of the request payload is possible, as long as it is done in a backward compatible way, meaning it has a default value and can be omitted safely.
docs/API_POLICY.md
Outdated
| - Breaking changes are those when users have to change their implementation as per the changes in API. for eg. removal of a field from response, removing an API, removing a query param of an API. | ||
| - These changes will be introduced as a new version of the APIs. | ||
| - If current version of APIs is `/v1` and an API is going to be removed then all other APIs will be moved to `/v2`. | ||
| Users of v1 will be able to use old versioned APIs for 9 months then they will be removed. |
There was a problem hiding this comment.
Are we saying that one a v2 of an API is out, 9 months after, v1 gets removed ?
(note : we should probably use "at least 9 month" 😝 )
There was a problem hiding this comment.
yup once v2 is out v1 will get removed after 9 months.
There was a problem hiding this comment.
but let's say there is some breaking change in one of the API in v1 so increment the version to v2 so all other v1 APIs would also be incremented or just the one?
There was a problem hiding this comment.
my understanding was we increment all the APIs to v2 and then after 9 months remove all the v1 APIs
There was a problem hiding this comment.
yeah, it is probably better to bump the API version for all at the same time.
| - `/v1/resource/<catalog>/<kind>/<name>/<version>` | ||
| - `/v1/resource/<id>/versions` | ||
| - `/v1/resource/version/<versionID>` | ||
| - `/v1/schema/swagger.json` |
There was a problem hiding this comment.
Is this an API or just a file 😉
There was a problem hiding this comment.
it is an API that returns a file on the server 😄
This adds document which proposes a policy regarding making updates to the APIs of this repo. Signed-off-by: Shivam Mukhade <smukhade@redhat.com>
|
/lgtm |
|
[APPROVALNOTIFIER] This PR is APPROVED This pull-request has been approved by: vdemeester The full list of commands accepted by this bot can be found here. The pull request process is described here
Needs approval from an approver in each of these files:
Approvers can indicate their approval by writing |
tekton-robot
added
the
approved
Signed-off-by: Shivam Mukhade smukhade@redhat.com
Submitter Checklist
These are the criteria that every PR should meet, please check them off as you
review them:
See the contribution guide for more details.