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 ;)

1. ESTful
and it’s fine
We are not
anymore...
Thibault Ducret
Backend software developer

3. Notre-Dame de Paris
April 2019
Hubert Hitier/AFP

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

8. DELETE /datasets/1

9. DELETE /datasets/1
DELETE /datasets/2
DELETE /datasets/3
DELETE /datasets/4
DELETE /datasets/5
DELETE /datasets/6
DELETE /datasets/7
DELETE /datasets/8
DELETE /datasets/9
DELETE /datasets/10
DELETE /datasets/11
DELETE /datasets/12
DELETE /datasets/13
DELETE /datasets/14
DELETE /datasets/15
DELETE /datasets/16
DELETE /datasets/17
DELETE /datasets/18
DELETE /datasets/19
DELETE /datasets/20
DELETE /datasets/21
DELETE /datasets/22
DELETE /datasets/23
DELETE /datasets/24
DELETE /datasets/25
DELETE /datasets/26
DELETE /datasets/27
DELETE /datasets/28
DELETE /datasets/29
DELETE /datasets/30
DELETE /datasets/31
DELETE /datasets/32
DELETE /datasets/33
DELETE /datasets/34
DELETE /datasets/35
DELETE /datasets/36
DELETE /datasets/37
DELETE /datasets/38
DELETE /datasets/39
DELETE /datasets/40
DELETE /datasets/41
DELETE /datasets/42
DELETE /datasets/43
DELETE /datasets/44
DELETE /datasets/45
DELETE /datasets/46
DELETE /datasets/47
DELETE /datasets/48
DELETE /datasets/49
DELETE /datasets/50
DELETE /datasets/51
DELETE /datasets/52
DELETE /datasets/53
DELETE /datasets/54
DELETE /datasets/55
DELETE /datasets/56
DELETE /datasets/57
DELETE /datasets/58
DELETE /datasets/59
DELETE /datasets/60
DELETE /datasets/61
DELETE /datasets/62
DELETE /datasets/63
DELETE /datasets/64
DELETE /datasets/65
DELETE /datasets/66
DELETE /datasets/67
DELETE /datasets/68
DELETE /datasets/69
DELETE /datasets/70
DELETE /datasets/71
DELETE /datasets/72
DELETE /datasets/73
DELETE /datasets/74
DELETE /datasets/75
DELETE /datasets/76
DELETE /datasets/77
DELETE /datasets/78
DELETE /datasets/79
DELETE /datasets/80
DELETE /datasets/81
DELETE /datasets/82
DELETE /datasets/83
DELETE /datasets/84
DELETE /datasets/85
DELETE /datasets/86
DELETE /datasets/87
DELETE /datasets/88
DELETE /datasets/89
DELETE /datasets/90
DELETE /datasets/91
DELETE /datasets/92
DELETE /datasets/93
DELETE /datasets/94
DELETE /datasets/95
DELETE /datasets/96
DELETE /datasets/97
DELETE /datasets/98
DELETE /datasets/99
DELETE /datasets/100

11. Rest in peace
REST

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

13. POST /delete-datasets {"datasets": [1, 2, 3, 4..100]}
POST /delete-datasets-permanently {"datasets": [1, 2, 3, 4..100]}

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

15. Delair.ai has
the most simple
API style ever made*
*according to the Delair CTO

20. REST
thibault.ducret@delair.aero
« An efficient and
well-documented
API is better than
a RESTful API »