The API routing does not feel RESTful

[thibaultcha]

Writing the Getting Started guide raised a concern about the structure of our routes. Having to explain:

Nope

# Create an API:
$ curl -i -X POST \
  --url http://localhost:8001/apis/ \
  --data 'name=mockbin&target_url=http://mockbin.com/&public_dns=mockbin.com'
HTTP/1.1 201 Created
...

# Add a plugin to it:
# Make sure the api_id parameter matches the one of mockbin created earlier
$ curl -i -X POST \
  --url http://localhost:8001/plugins/ \
  --data 'name=headerauth&api_id=<api_id>&value.header_names=apikey'
HTTP/1.1 201 Created
...

Feels wrong. Having to pass the api_id as a form parameter does not feel REST. It would be nicer to do:

Yep

# Create an API:
$ curl -i -X POST \
  --url http://localhost:8001/apis/ \
  --data 'name=mockbin&target_url=http://mockbin.com/&public_dns=mockbin.com'
HTTP/1.1 201 Created
...

# Add a plugin to it:
$ curl -i -X POST \
  --url http://localhost:8001/apis/mockbin/plugins/ \
  --data 'name=headerauth&value.header_names=apikey'
HTTP/1.1 201 Created
...

Here the route became: /apis/{api_name}/plugins/. Since plugins can also be attached to applications, do we have to create the applications/{id}/apis/{api_id/api_name}/plugins/ route? Probably.

Same for applications and accounts:

Nope

# Create an account
$ curl -i -X POST \ 
  --url http://localhost:8001/accounts/
  --data ''
HTTP/1.1 201 Created
...

# And an application
# Make sure the given account_id matches the freshly created account
$ curl -i -X POST \
  --url http://localhost:8001/applications/
  --data 'public_key=123456&account_id=<account_id>'
HTTP/1.1 201 Created
...

Becomes:

Yep

# Create an account
$ curl -i -X POST \ 
  --url http://localhost:8001/accounts/
  --data ''
HTTP/1.1 201 Created
...

# And an application
$ curl -i -X POST \
  --url http://localhost:8001/accounts/{account_id}/applications/
  --data 'public_key=123456'
HTTP/1.1 201 Created
...

New route: /accounts/{account_id/provider_id}/applications/.

[subnetmarco]

We would still need to provide generic endpoints like /plugins/ or /applications/: for example, in your examples above how would you retrieve an application by ID without knowing the owner account (or by public_key, or secret_key) ?

We need to learn what are the use-cases we want to support (does it make sense to search an application by ID in the first place?), then we need to find the right mix of simplicity and RESTfulness without necessarily complicating the user experience.

[thibaultcha]

Yes of course, /plugins/ and others would stay.

[wilmoore]

While at it, it would be nice to also consider accepting parameters via Content-Type: application/json vs. Content-Type: application/x-www-form-urlencoded.

[nijikokun]

@thibaultcha You are passing the identifiers twice (once in uri, and another in the payload) in your yep examples, which I think you meant the opposite, otherwise there would be no benefit.

[thibaultcha]

@wilmoore This is now done since #236! The API supports PATCH, PUT, POST all in JSON or form-encoded.

[wilmoore]

@thibaultcha 👍

[DavidTPate]

👍

[thibaultcha]

So, among many other things, the API now has an improved support for the plugins_configurations (plugins enabled on some APIs, they contain the plugin config for that API).

It means:

GET PUT POST
/apis/{:name | :id}/plugins/

GET PATCH DELETE
/apis/{:name | :id}/plugins/{:name | :id}

Does it still make sense to support the old route:

GET PUT POST
/plugins_configurations/

GET PATCH DELETE
/plugins_configurations/:id

or not? One use case I can see for GET on /plugins_configurations/ is for listing all plugins enabled across all the APIs, but that would be all.

[ahmadnassri]

@thibaultcha i would keep support for old route in the next release, and remove it in the following release, just for backward compatibility.

as for all plugins, I see that as a special endpoint, perhaps simply GET /plugins

[subnetmarco]

If we use /apis/{:name | :id}/plugins/ as opposed to /apis/{:name | :id}/plugins_configurations/ then also the general route should be called /plugins instead of /plugins_configurations if we decide to keep it.

[ahmadnassri]

@thefosk perhaps the general route is only a GET for listing, and keep all the actual plugin interactions (PUT, DELETE, POST, etc ...) per API route.

[thibaultcha]

The reasoning we had is that in the context of apis/:api/plugins/, we know we are talking about configuration of a plugin on top of an API. Where plugins_configurations was named like this in the first place because we wanted to make it clear what it was about.

[thibaultcha]

PR opened with some massive changes: #257

[thibaultcha]

Closing this now that #257 has been merged. Please report any potential problem in a new issue!