![octo.com
REST
F
U
L
AP
I
D
ES
I
G
N
URLs.
You should use nouns, not verbs (vs SOAP-RPC).
GET /orders not /getAllOrders
NOUNS
You should use plural nouns, not singular nouns,
to manage two different types of resources:
Collection resource: /users
Instance resource: /users/007
You should remain consistent.
GET /users/007 not GET /user/007
PLURALS
user(s)
You may choose between snake_case or
camelCase for attributes and parameters,
but you should remain consistent.
CONSISTENT
CASE
GET /orders?id_user=007
or GET /orders?idUser=007
POST/orders {id_user:007}
or POST/orders {idUser:007}
If you have to use more than one word in URL,
you should use spinal-case (some servers
ignore case).
POST /specific-orders
You should make versioning mandatory in the
URL at the highest scope (major versions).
You may support at most two versions at the
same time (Native apps need a longer cycle).
GET /v1/orders
VERSIONING
You should leverage the hierarchical nature
of the URL to imply structure (aggregation or
composition). Ex: an order contains products.
GET /orders/1234/products/1
HIERARCHICAL
STRUCTURE
/V1/ /V2/
/V3/ /V4/
POST is used to Create an instance of a collection.
The ID isn’t provided, and the new resource
location is returned in the “Location” Header.
POST /orders {state:running, «id_user:007}
201 Created
Location: https://api.fakecompany.com/orders/1234
But remember that, if the ID is specified by the
client, PUT is used to Create the resource.
PUT /orders/1234
201 Created
PUT is used for Updates to perform a full
replacement.
PUT /orders/1234 {state:paid, id_user:007}
200 Ok
PATCH is commonly used for partial Update.
PATCH /orders/1234 {state:paid}
200 Ok
Use HTTP verbs for CRUD operations (Create/Read/Update/Delete).
CRUD-LIKE OPERATIONS
HTTP VERB COLLECTION: /ORDERS INSTANCE : /ORDER/{ID}
GET
POST
PUT
PATCH
DELETE
Read a list of orders. 200 OK.
Create a new order. 201 Created.
-
-
-
Read the details of a single order. 200 OK.
-
Full Update: 200 OK./ Create a specific order:
201 Created.
Partial Update. 200 OK.
Delete order. 204 OK.
GET is used to Read a collection.
GET /orders
200 Ok
[{id:1234, state:paid}
{id:5678, state:running}]
GET is used to Read an instance.
GET /orders/1234
200 Ok
{id:1234, state:paid}
nouns
verbs](https://image.slidesharecdn.com/2023refcardrestfulapidesignweboutfit-230427094915-47052f7b/85/RefCard-RESTful-API-Design-6-320.jpg)
![octo.com
REST
F
U
L
AP
I
D
ES
I
G
N
Other key concepts.
Content negotiation is managed only in a pure
RESTful way. The client asks for the required
content, in the Accept header, in order of
preference. Default format is JSON.
Accept: application/json, text/plain not /orders.json
CONTENT
NEGOTIATION
UseISO8601standardforDate/Time/Timestamp:
1978-05-10T06:06:06+00:00 or 1978-05-10
Add support for different Languages.
Accept-Language: fr-CA, fr-FR not ?language=fr
I18N
Use CORS standard to support REST API
requests from browsers (js SPA…).
But if you plan to support Internet Explorer 7/8
or 9, you shall consider specifics endpoints to
add JSONP support.
All requests will be sent with a GET method!
Content negotiation cannot be handled with
Accept header in JSONP.
Payload cannot be used to send data.
CROSS-ORIGIN
REQUESTS
POST /orders and /orders.jsonp?method=POSTcallback=foo
GET /orders and /orders.jsonp?callback=foo
GET /orders/1234 and /orders/1234.jsonp?callback=foo
PUT /orders/1234 and /orders/1234.jsonp?method=PUTcallback=foo
Warning: a web crawler could easily damage your application with a method parameter.
Make sure that an OAuth2 access_token is required, and an OAuth2 client_id as well.
Your API should provide Hypermedia links in order to be completely discoverable. But keep
in mind that a majority of users wont probably use those hyperlinks (for now), and will read
the API documentation and copy/paste call examples.
So, each call to the API should return in the Link header every possible state of the applica-
tion from the current state, plus self.
You may use RFC5988 Link notation to implement HATEOAS :
HATEOAS
GET /users/007
200 Ok
{ id:007, firstname:Mario,...}
Link : https://api.fakecompany.com/v1/users; rel=self; method:GET,
https://api.fakecompany.com/v1/addresses/42; rel=addresses; method:GET,
https://api.fakecompany.com/v1/orders/1234; rel=orders; method:GET
In a few use cases we have to consider operations
or services rather than resources.
You may use a POST request with a verb at the
end of the URI.
“NON RESOURCE”
SCENARIOS
POST /emails/42/send
POST /calculator/sum [1,2,3,5,8,13,21]
POST /convert?from=EURto=USDamount=42
However, you should consider using RESTful
resources first before going this way.
RESTFUL WAY](https://image.slidesharecdn.com/2023refcardrestfulapidesignweboutfit-230427094915-47052f7b/85/RefCard-RESTful-API-Design-8-320.jpg)
RefCard RESTful API Design
- 2. octo.com REST F U L AP I D ES I G N As soon as we start working on an API, design issues arise. A robust and strong design is a key factor for API success. A poorly designed API will indeed lead to misuse or – even worse – no use at all by its intended clients: application developers. Creating and providing a state of the art API requires taking into account: RESTful API principles as described in the literature (Roy Fielding, Leonard Richardson, Martin Fowler, HTTP specification…) The API practices of the Web Giants Nowadays, two opposing approaches are seen. “Purists” insist upon following REST principles without compromise. “Pragmatics” prefer a more practical approach, to provide their clients with a more usable API. The proper solution often lies in between. Designing a REST API raises questions and issues for which there is no universal answer. REST best practices are still being debated and consolidated, which is what makes this job fascinating. To facilitate and accelerate the design and development of your APIs, we share our vision and beliefs with you in this Reference Card. They come from our direct experience on API projects. RESTful API Design.
- 3. octo.com REST F U L AP I D ES I G N Why an API strategy ? “Anytime,Anywhere,Any device” are the key problems of digitalisation. API is the answer to “Business Agility” as it allows to build rapidly new GUI for upcoming devices. An API layer enables Cross device Cross channel 360° customer view Open API allows To outsource innovation To create new business models Embrace WOA “Web Oriented Architecture” Build a fast, scalable secured REST API Based on: REST, HATEOAS, Stateless decoupled µ-services, Asynchronous patterns, OAuth2 and OpenID Connect protocols Leverage the power of your existing web infrastructure DISCLAMER This Reference Card doesn’t claim to be absolutely accurate. The design concepts exposed result from our previous work in the REST area. Please check out our blog http://blog.octo.com, and feel free to comment or challenge this API cookbook. We are really looking forward to sharing with you.
- 4. octo.com REST F U L AP I D ES I G N HTTP STATUS CODE DESCRIPTION SUCCESS 200 OK • Basic success code. Works for the general cases. • Especially used on successful first GET requests or PUT/PATCH updated content. 201 Created • Indicates that a resource was created. Typically responding to PUT and POST requests. 202 Accepted • Indicates that the request has been accepted for processing. • Typically responding to an asynchronous processing call (for a better UX and good performances). 204 No Content • The request succeeded but there is nothing to show. Usually sent after a successful DELETE. 206 Partial Content • The returned resource is incomplete. Typically used with paginated resources. HTTP Status codes. SERVER ERROR 400 Bad Request General error for a request that cannot be processed. CLIENT ERROR GET /bookings?paid=true → 400 Bad Request → {error:invalid_request, error_description:There is no ‘paid’ property} 401 Unauthorized I do not know you, tell me who you are and I will check your permissions. GET /bookings/42 → 401 Unauthorized → {error”:no_credentials, error_description:You must be authenticated} 403 Forbidden Your rights are not sufficient to access this resource. GET /bookings/42 → 403 Forbidden → {error:protected_resource, error_description:You need sufficient rights} 404 Not Found The resource you are requesting does not exist. GET /hotels/999999 → 404 Not Found → {error:not_found, error_description: The hotel ‘999999’ does not exist} 405 Method Not Allowed Either the method is not supported or relevant on this resource or the user does not have the permission. PUT /hotels/999999 → 405 Method Not Allowed → {error:not_implemented, error_description:Hotel creation not implemented} 406 Not Acceptable There is nothing to send that matches the Accept-* headers. For example, you requested a resource in XML but it is only available in JSON. GET /hotels Accept-Language: cn → 406 Not Acceptable → {error: not_acceptable, error_description:Available languages: en, fr} The request seems right, but a problem occurred on the server. The client cannot do anything about that. GET /users → 500 Internal server error → {error:server_error, error_description:Oops! Something went wrong…} ERROR 418 I’m a teapot 500 Internal Server Error
- 5. octo.com REST F U L AP I D ES I G N General concepts. Anyone should be able to use your API without having to refer to the documentation. Use standard, concrete and shared terms, not your specific business terms or acronyms. Never allow application developers to do things more than one way. Design your API for your clients (Application developers), not for your data. Target main use cases first, deal with exceptions later. GET /orders, GET /users, GET /products, ... KISS OAuth2/OIDC HTTPS You should use OAuth2 to manage Authorization. OAuth2 matches 99% of requirements and client typologies, don’t reinvent the wheel, you’ll fail. You should use HTTPS for every API/OAuth2 request. You may use OpenID Connect to handle Authentication. SECURITY CURL You should use CURL to share examples, which you can copy/paste easily. GRANULARITY Medium grained resources You should use medium grained, not fine nor coarse. Resources shouldn’t be nested more than two levels deep: GET /users/007 { id”:007, first_name”:James, name:Bond, address:{ street:”Horsen Ferry Road, ”city:{name:London} } } API DOMAIN NAMES You may consider the following five subdomains: Production: https://api.fakecompany.com Test: https://api.sandbox.fakecompany.com Developer portal: https://developers.fakecompany.com Production: https://oauth2.fakecompany.com Test: https://oauth2.sandbox.fakecompany.com www. CURL –X POST -H Accept: application/json -H Authorization: Bearer at-80003004-19a8-46a2-908e-33d4057128e7 -d ‘{state:running}’ https://api.fakecompany.com/v1/users/007/orders?client_id=API_KEY_003
- 6. octo.com REST F U L AP I D ES I G N URLs. You should use nouns, not verbs (vs SOAP-RPC). GET /orders not /getAllOrders NOUNS You should use plural nouns, not singular nouns, to manage two different types of resources: Collection resource: /users Instance resource: /users/007 You should remain consistent. GET /users/007 not GET /user/007 PLURALS user(s) You may choose between snake_case or camelCase for attributes and parameters, but you should remain consistent. CONSISTENT CASE GET /orders?id_user=007 or GET /orders?idUser=007 POST/orders {id_user:007} or POST/orders {idUser:007} If you have to use more than one word in URL, you should use spinal-case (some servers ignore case). POST /specific-orders You should make versioning mandatory in the URL at the highest scope (major versions). You may support at most two versions at the same time (Native apps need a longer cycle). GET /v1/orders VERSIONING You should leverage the hierarchical nature of the URL to imply structure (aggregation or composition). Ex: an order contains products. GET /orders/1234/products/1 HIERARCHICAL STRUCTURE /V1/ /V2/ /V3/ /V4/ POST is used to Create an instance of a collection. The ID isn’t provided, and the new resource location is returned in the “Location” Header. POST /orders {state:running, «id_user:007} 201 Created Location: https://api.fakecompany.com/orders/1234 But remember that, if the ID is specified by the client, PUT is used to Create the resource. PUT /orders/1234 201 Created PUT is used for Updates to perform a full replacement. PUT /orders/1234 {state:paid, id_user:007} 200 Ok PATCH is commonly used for partial Update. PATCH /orders/1234 {state:paid} 200 Ok Use HTTP verbs for CRUD operations (Create/Read/Update/Delete). CRUD-LIKE OPERATIONS HTTP VERB COLLECTION: /ORDERS INSTANCE : /ORDER/{ID} GET POST PUT PATCH DELETE Read a list of orders. 200 OK. Create a new order. 201 Created. - - - Read the details of a single order. 200 OK. - Full Update: 200 OK./ Create a specific order: 201 Created. Partial Update. 200 OK. Delete order. 204 OK. GET is used to Read a collection. GET /orders 200 Ok [{id:1234, state:paid} {id:5678, state:running}] GET is used to Read an instance. GET /orders/1234 200 Ok {id:1234, state:paid} nouns verbs
- 7. octo.com REST F U L AP I D ES I G N Query strings. SEARCH You should use /search keyword to perform a search on a specific resource. GET /restaurants/search?type=thai You may use the “Google way” to perform a global search on multiple resources. GET /search?q=running+paid SORT PAGINATION You may use a range query parameter. Pagination is mandatory: a default pagination has to be defined, for example: range=0-25. The response should contain the following headers: Link, Content-Range, Accept-Range. Note that pagination may cause some unexpected behavior if many resources are added. PARTIAL RESPONSES Youshouldusepartialresponsessodevelopers can select which information they need, to optimize bandwidth (crucial for mobile development). /orders?range=48-55 206 Partial Content Content-Range: 48-55/971 Accept-Range: order 10 Link : https://api.fakecompany.com/v1/orders?range=0-7; rel=first, https://api.fakecompany.com/v1/orders?range=40-47; rel=prev, https://api.fakecompany.com/v1/orders?range=56-64; rel=next, https://api.fakecompany.com/v1/orders?range=968-975; rel=last GET /users/007?fields=firstname,name,address(street) 200 OK { id:007, firstname:James, name:Bond, address:{street:Horsen Ferry Road} } FILTERS You ought to use ‘?’ to filter resources GET /orders?state=payedid_user=007 or(multipleURIsmayrefertothesameresource) GET /users/007/orders?state=paied Use ?sort =atribute1,atributeN to sort resources. By default resources are sorted in ascending order. Use ?desc=atribute1,atributeN to sort resources in descending order GET /restaurants?sort=rating,reviews,name;desc=rate,reviews URL RESERVED WORDS : FIRST, LAST, COUNT Use /first to get the 1st element GET /orders/first 200 OK {id:1234, state:paid} Use /last to retrieve the latest resource of a collection GET /orders/last 200 OK {id:5678, state:running} Use /count to get the current size of a collection GET /orders/count 200 OK {2}
- 8. octo.com REST F U L AP I D ES I G N Other key concepts. Content negotiation is managed only in a pure RESTful way. The client asks for the required content, in the Accept header, in order of preference. Default format is JSON. Accept: application/json, text/plain not /orders.json CONTENT NEGOTIATION UseISO8601standardforDate/Time/Timestamp: 1978-05-10T06:06:06+00:00 or 1978-05-10 Add support for different Languages. Accept-Language: fr-CA, fr-FR not ?language=fr I18N Use CORS standard to support REST API requests from browsers (js SPA…). But if you plan to support Internet Explorer 7/8 or 9, you shall consider specifics endpoints to add JSONP support. All requests will be sent with a GET method! Content negotiation cannot be handled with Accept header in JSONP. Payload cannot be used to send data. CROSS-ORIGIN REQUESTS POST /orders and /orders.jsonp?method=POSTcallback=foo GET /orders and /orders.jsonp?callback=foo GET /orders/1234 and /orders/1234.jsonp?callback=foo PUT /orders/1234 and /orders/1234.jsonp?method=PUTcallback=foo Warning: a web crawler could easily damage your application with a method parameter. Make sure that an OAuth2 access_token is required, and an OAuth2 client_id as well. Your API should provide Hypermedia links in order to be completely discoverable. But keep in mind that a majority of users wont probably use those hyperlinks (for now), and will read the API documentation and copy/paste call examples. So, each call to the API should return in the Link header every possible state of the applica- tion from the current state, plus self. You may use RFC5988 Link notation to implement HATEOAS : HATEOAS GET /users/007 200 Ok { id:007, firstname:Mario,...} Link : https://api.fakecompany.com/v1/users; rel=self; method:GET, https://api.fakecompany.com/v1/addresses/42; rel=addresses; method:GET, https://api.fakecompany.com/v1/orders/1234; rel=orders; method:GET In a few use cases we have to consider operations or services rather than resources. You may use a POST request with a verb at the end of the URI. “NON RESOURCE” SCENARIOS POST /emails/42/send POST /calculator/sum [1,2,3,5,8,13,21] POST /convert?from=EURto=USDamount=42 However, you should consider using RESTful resources first before going this way. RESTFUL WAY
- 9. octo.com REST F U L AP I D ES I G N For more information, check out our blog OCTO Talks READ OUR BLOG POST - EN LIRE L’ARTICLE DE BLOG - FR
- 10. octo.com REST F U L AP I D ES I G N We believe that API IS THE ENGINE OF DIGITAL STRATEGY WE KNOW that the Web infiltrates AND transforms COMPANIES WE WORK TOGETHER, with passion, TO CONNECT BUSINESS IT We help you CREATE OPPORTUNITIES AND EMBRACE THE WEBInside Out.
- 11. octo.com REST F U L AP I D ES I G N OCTO Technology “ Dans un monde complexe aux ressources finies, nous recherchons ensemble de meilleures façons d'agir. Nous œuvrons à concevoir et à réaliser les produits numériques essentiels au progrès de nos clients et à l'émergence d'écosystèmes vertueux” – Manifeste OCTO Technology - CABINET DE CONSEIL ET DE RÉALISATION IT Paris Toulouse Hauts-de-France IMPLANTATIONS 1OOO OCTOS OCTO EN TÊTE DU PALMARÈS 3 CONFÉRENCES FORMATION La conférence tech par OCTO 3 6x
- 12. octo.com REST F U L AP I D ES I G N © OCTO Technology 2015 Les informations contenues dans ce document présentent le point de vue actuel d'OCTO Technology sur les sujets évoqués, à la date de publication. Tout extrait ou diffusion partielle est interdit sans l'autorisation préalable d'OCTO Technology. Les noms de produits ou de sociétés cités dans ce document peuvent être les marques déposées par leurs propriétaires respectifs. Conçu, réalisé et édité par OCTO Technology.