Project

General

Profile

Question #1547

API: API Evolution

Added by Bernhard Koschiček-Krombholz 7 months ago. Updated about 2 months 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

Precedes Feature #1549: API: deprecation of node and subunit functionsClosed2021-07-15Actions

History

#1

Updated by Bernhard Koschiček-Krombholz 7 months 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.

#2

Updated by Bernhard Koschiček-Krombholz 7 months ago

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

Updated by Alexander Watzinger 4 months ago

  • Status changed from New to Assigned
#4

Updated by Bernhard Koschiček-Krombholz about 2 months 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.

#5

Updated by Bernhard Koschiček-Krombholz about 2 months ago

  • Status changed from Assigned to Closed
#6

Updated by Alexander Watzinger about 2 months ago

  • Target version deleted (API)

Removing closed question from roadmap.

Also available in: Atom PDF