Project

General

Profile

Question #1547

API: API Evolution

Added by Bernhard Koschiček-Krombholz 2 months ago. Updated 3 days ago.

Status:
Assigned
Priority:
Low
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 Question #1549: API: deprecation of node_entities and node_entities_allAssigned2021-07-15Actions

History

#1

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

  • Precedes Question #1549: API: deprecation of node_entities and node_entities_all added
#3

Updated by Alexander Watzinger 3 days ago

  • Status changed from New to Assigned

Also available in: Atom PDF