Project

General

Profile

Actions

Question #1547

closed

API: API Evolution

Added by Bernhard Koschiček-Krombholz over 3 years ago. Updated almost 3 years ago.

Status:
Closed
Priority:
Normal
Category:
API
Target version:
-
Start date:
2021-07-14
Estimated time:

Description

I have read about API evolution. It is not good practice to user version numbers, either in URI nor in HTTP Headers. The best design would be to only add things and not delete anything unless it is absolutely necessary. Endpoints and json objects should be marks with a deprecation note to tell the clients that this resource is no longer up-to-date. This should give the clients time to adjust their applications. This is also supported since OpenAPI 3.0 and since 2018 for json.

This in mind I like to discuss the possiblity to remove the version part of the URL. So /api/0.2/ will be only /api/.

Before this could happen, we need to work together, to make the API understandable and easy to use.


Related issues 1 (0 open1 closed)

Precedes OpenAtlas - Feature #1549: API: deprecation of node and subunit functionsClosedBernhard Koschiček-Krombholz2021-07-15Actions
Actions #1

Updated by Bernhard Koschiček-Krombholz about 3 years ago

Thoughts:
If the API should be easily understandable, it would be best when one can form sentences. Like, we declare our definitions and variables in the code. So we look into some like:

/api/get_entities_by_code/actor
/api/get_entity/23
/api/get_entities_linked_to_entity/43
/api/get_entity_by_system_class/person
/api/get_node_overview/
/api/get_subunits_of_entity/24534
/api/get_subunit_hierarchy_of_entity/24534
/api/get_class_mapping
...

One thing is always repeating itself:_get_, but it would be better understandable.

Another possibility could, that we sort the endpoints, like we did in the documentation on swagger hub.

/api/entity/23
/api/entities/by_code/actor
/api/entities/by_class/E18
/api/entities/of_type/52342
/api/entities/linked_to_entity/92
/api/entities/divide_by_geoms/
/api/entities/query/?classes=E18&code=actor&entities=1254123&entities=12312
/api/subunits/place/53

The advantage of this approach is, that the client knows from the path, what the endpoint will provide and how it will look like.

Actions #2

Updated by Bernhard Koschiček-Krombholz about 3 years ago

  • Precedes Feature #1549: API: deprecation of node and subunit functions added
Actions #3

Updated by Alexander Watzinger about 3 years ago

  • Status changed from New to Assigned
Actions #4

Updated by Bernhard Koschiček-Krombholz almost 3 years ago

For the sake of simplicity and usability, the API will further provide a version system. There will be always a stable version, where features can be added, but no breaking changes will occur. Parallel to that, there can be a new version, which is under development. Mostly it is a copy of the stable version, but breaking changes can occur. This will all be documented in API wiki page.
If an endpoint or parameter will be changed or deleted in the new version, it will be marked as deprecated in the stable version and also an issue of its deprecation will be created.

Currently, version 0.2 is stable, and version 0.3 is at a beta stage.

Actions #5

Updated by Bernhard Koschiček-Krombholz almost 3 years ago

  • Status changed from Assigned to Closed
Actions #6

Updated by Alexander Watzinger almost 3 years ago

  • Target version deleted (208)

Removing closed question from roadmap.

Actions

Also available in: Atom PDF