Should we structure our APIs ?

[zak39]

After propositions by @StCyr in this PR : https://github.com/arawa/workspace/pull/72 .

He would like to add /api/<resource> in the route. But, for developers it can be misleading. Because, in a HTTP response we can have ;

• Informations on HTTP status ;
• Which verb using ;
• Different error messages ;
• A json different according to HTTP Response ;
• And so on.

For examples :

1. This here a Jira Cloud Platform's creating issue API : https://developer.atlassian.com/cloud/jira/platform/rest/v3/api-group-issues/#api-rest-api-3-issue-post-responses . We can see there is a status code to do if the resource is created or not. But also, there is the different message according to HTP response.

2. In an API, we have to send a message to developer / user to guide him. This here an example a response GitHub's API to create a project :

{
"message": "Requires authentication",
"documentation_url": "https://developer.github.com/v3/repos/#edit"
}

Here, the message indicates to developer / user has to input his credentials.

3. An API has to use the status code HTTP which is standard (200 / 201 : creating, 200 : patching, 409 : One request is in conflict with the current state of server ;

4. And so on.

I don't have skills to know everything. But I know it's very important to structure APIs if we use them.

For example of my response after creating a project space :

{
  "space": "Galadriel",
  "id_space": 213,
  "groups": {
    "GE-Galadriel": 31,
    "U-Galadriel": 31
  },
  "space_advanced_permissions": true,
  "space_assign_groups": [
    "GE-Galadriel",
    "U-Galadriel"
  ],
  "acl": {
    "state": true,
    "group_manage": "GE-Galadriel"
  },
  "statuscode": 201
}

Here I write the statuscode to root of json. Maybe it's very interesting to write as it :

{
  "space": "Galadriel",
  "id_space": 213,
  "groups": {
    "GE-Galadriel": 31,
    "U-Galadriel": 31
  },
  "space_advanced_permissions": true,
  "space_assign_groups": [
    "GE-Galadriel",
    "U-Galadriel"
  ],
  "acl": {
    "state": true,
    "group_manage": "GE-Galadriel"
  },
  "http": {
      "statuscode": 201,
      "message" : "The space is created"
    }
}

What do you think ?

How to build our structure API ?

[zak39]

@StCyr : I don't have it's a good idea to use ApiController.php ( https://docs.nextcloud.com/server/21/developer_manual/digging_deeper/rest_apis.html?highlight=apicontroller ) for this issue ?

[LivOriona]

Is this issue still relevant? If yes, can you explain me why?