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