OpenAtlas

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.

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.