API URI structure

[michael-pisman]

Which structure should be used for the API endpoints: hierarchical vs flat.
Both are commonly used. This is in regard to API endpoints and not the front-end client(a Website) URL structure, so SEO, search engine crawlers, etc are not considered. The main focus is to provide a better(more intuitive) structure for front-end developers.

The current layout can be found at https://unipoll-api.1cl.cc/docs

Hierarchical structure:

Tree like structure that defines resource path by their location.

GET /workspaces return the list of all workspaces
GET /workspaces/{id} return the workspace with specified ID (including groups, members, polls, etc)
GET /workspaces/{id}/members return the list of members from the workspace with specified ID
GET /workspaces/{id}/groups return the list of groups from the workspace with specified ID
GET /workspaces/{id}/groups/{id} return the group (including members, policies, etc) with specified ID
GET /workspaces/{id}/groups/{id}/members return the list of members from the group with specified ID

Pros

• Might be more intuitive, since this structure closely resembles how and where the resources are stored
• ?

Cons

• Long URLs
• Higher number of endpoints, which means, client might need to use documentation more often
• Redundant IDs, like in the case of getting a group by ID, the client must also specify the ID of the workspace even though it's not needed

Flat Structure:

GET /workspaces return the list of all workspaces
GET /workspaces/{id} return the workspace with specified ID (including groups, members, polls, etc)
GET /members?workspace={id} return the list of members from the workspace with specified ID
GET /groups?workspace={id} return the list of groups from the workspace with specified ID
GET /groups/{id} return the group (including members, policies, etc) with specified ID
GET /members?group={id} return the list of members from the group with specified ID

Pros

• Short URLs
• Overall would include less endpoints, which makes it easier to memorize the API

Cons

• Higher use of query parameters

Hybrid structure:

Current structure, which combines both options and is neither intuitive or correct use of URI.

GET /workspaces - return the list of all workspaces
GET /workspaces/{id} return the workspace with specified ID (including groups, members, polls, etc)
GET /workspaces/{id}/members return the list of members from the workspace with specified ID
GET /workspaces/{id}/groups return the list of groups from the workspace with specified ID
GET /groups/{id} return the group (including members, policies, etc) with specified ID
GET /groups/{id}/members return the list of members from the group with specified ID

Feel free to suggest other advantages/disadvantages of either method.

[michael-pisman]

The API will support multiple versions, the version v1 will follow string Hierarchical structure, while the default version of the API, v2, will follow Flat structure.

Related Issues: csed-ucm/psephos#79, csed-ucm/psephos#80, csed-ucm/psephos#82