Because everything is not a “resource” on our drone platform, we were tired of maintaining our RESTFul API.
I’ll talk about the pros and cons of designing an API following the action pattern. Here are a few (- is a con, + is a pro) :
– it is not usual… (we have to deal with developer frustration :)
– there are much more API routes than for RESTFul API (/pet becomes /create-pet, /delete-pet, /update-pet…)
+ it is easier to apply a specific authorization policy on an action (no need to check the content of the request : the route is allowed or not)
+ it’s easier to add a new feature, and not trying to make it fit to the RESTFul principles (especially if more than one resource is involved in this operation)
+ we don’t have to remember all the RESTFul-related status codes. If it’s ok, it’s 200. For every other applicative error, we use the same status code, and maintain a list of error keywords.
+ no more PUT, DEL, UPDATE headaches : we use only POST and GET
+ and more ;)
6. {
"_id": "1",
"name": "My image",
"type": "image",
"acquisition_date": "2019-10-12T06:30:53.000Z",
"project": "2",
"components": [
{
"checksum": "461c5eaa3107c633db87ad5700f6c9b2",
"filename": "My image.jpg",
"size": 5466200,
"status": "available"
}
],
"horizontal_srs_wkt": "GEOGCS["WGS 84..."]]",
"creation_date": "2019-10-22T13:20:18.155Z",
"camera_parameters": [],
"geometry": {
"coordinates": [1, 2],
"type": "Point"
},
"ingestion": {"status": "processing"},
[...]
}
For every file stored, we create a dataset
7. # Create the dataset
POST /datasets {"name": "My image", "location": [1, 2]}
# Update the ingestion status
PATCH /datasets/1 {"ingestion_status": "available"}
# Improve the image location
PATCH /datasets/1 {"location": [1.1, 2.1]}
# Rename the dataset
PATCH /datasets/1 {"name": "A better name"}
With a RESTful API
12. POST /create-dataset {"name": "My image", "location": [1, 2]}
POST /update-dataset-status {"ingestion_status": "available"}
POST /update-dataset-location {"location": [1.1, 2.1]}
POST /rename-dataset {"name": "A better name"}
With our new API style
14. REST API Style API Style
Endpoint One per resource
/datasets
One per action
/create-dataset
Methods GET
PUT
PATCH
POST
DELETE
HEAD
CONNECT
TRACE
OPTIONS
POST
GET
Status codes 90+ status codes !
200
201
202
203
204
418 (☜ check it out)
…
6 status codes
200 : Operation successful
400 : Bad request
401 : Unauthenticated request
403 : Unauthorized request
404 : Not found
500: Internal server error