SlideShare a Scribd company logo
There
is
a
better
way
octo.com
Quick Reference Card
Res+ful
API
Design
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.
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.
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
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
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
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}
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
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
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.
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
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.

More Related Content

Similar to RefCard RESTful API Design

Understanding Identity in the World of Web APIs – Ronnie Mitra, API Architec...
Understanding Identity in the World of Web APIs – Ronnie Mitra,  API Architec...Understanding Identity in the World of Web APIs – Ronnie Mitra,  API Architec...
Understanding Identity in the World of Web APIs – Ronnie Mitra, API Architec...
CA API Management
 
distributing over the web
distributing over the webdistributing over the web
distributing over the web
Nicola Baldi
 
How APIs Can Be Secured in Mobile Environments
How APIs Can Be Secured in Mobile EnvironmentsHow APIs Can Be Secured in Mobile Environments
How APIs Can Be Secured in Mobile Environments
WSO2
 
RESTful Web Services
RESTful Web ServicesRESTful Web Services
RESTful Web Services
Gordon Dickens
 
API Workshop: Deep dive into REST APIs
API Workshop: Deep dive into REST APIsAPI Workshop: Deep dive into REST APIs
API Workshop: Deep dive into REST APIs
Tom Johnson
 
Automating Cloud Operations: Everything You Wanted to Know about cURL and REST
Automating Cloud Operations: Everything You Wanted to Know about cURL and RESTAutomating Cloud Operations: Everything You Wanted to Know about cURL and REST
Automating Cloud Operations: Everything You Wanted to Know about cURL and REST
Revelation Technologies
 
REST API Best Practices & Implementing in Codeigniter
REST API Best Practices & Implementing in CodeigniterREST API Best Practices & Implementing in Codeigniter
REST API Best Practices & Implementing in Codeigniter
Sachin G Kulkarni
 
Understanding and testing restful web services
Understanding and testing restful web servicesUnderstanding and testing restful web services
Understanding and testing restful web services
mwinteringham
 
REST in ( a mobile ) peace @ WHYMCA 05-21-2011
REST in ( a mobile ) peace @ WHYMCA 05-21-2011REST in ( a mobile ) peace @ WHYMCA 05-21-2011
REST in ( a mobile ) peace @ WHYMCA 05-21-2011
Alessandro Nadalin
 
Web Services Tutorial
Web Services TutorialWeb Services Tutorial
Web Services Tutorial
Lorna Mitchell
 
Service approach for development Rest API in Symfony2
Service approach for development Rest API in Symfony2Service approach for development Rest API in Symfony2
Service approach for development Rest API in Symfony2
Sumy PHP User Grpoup
 
Petr Dvořák: Mobilní webové služby pohledem iPhone developera
Petr Dvořák: Mobilní webové služby pohledem iPhone developeraPetr Dvořák: Mobilní webové služby pohledem iPhone developera
Petr Dvořák: Mobilní webové služby pohledem iPhone developera
WebExpo
 
- Webexpo 2010
- Webexpo 2010- Webexpo 2010
- Webexpo 2010
Petr Dvorak
 
Together Cheerfully to Walk with Hypermedia
Together Cheerfully to Walk with HypermediaTogether Cheerfully to Walk with Hypermedia
Together Cheerfully to Walk with Hypermedia
Vladimir Tsukur
 
Hacking Client Side Insecurities
Hacking Client Side InsecuritiesHacking Client Side Insecurities
Hacking Client Side Insecurities
amiable_indian
 
rest-api-basics.pptx
rest-api-basics.pptxrest-api-basics.pptx
rest-api-basics.pptx
FikiRieza2
 
Crafting APIs
Crafting APIsCrafting APIs
Crafting APIs
Tatiana Al-Chueyr
 
Web services tutorial
Web services tutorialWeb services tutorial
Web services tutorial
Lorna Mitchell
 
Web Services PHP Tutorial
Web Services PHP TutorialWeb Services PHP Tutorial
Web Services PHP Tutorial
Lorna Mitchell
 
APIs_ An Introduction.pptx
APIs_ An Introduction.pptxAPIs_ An Introduction.pptx
APIs_ An Introduction.pptx
AkashThorat25
 

Similar to RefCard RESTful API Design (20)

Understanding Identity in the World of Web APIs – Ronnie Mitra, API Architec...
Understanding Identity in the World of Web APIs – Ronnie Mitra,  API Architec...Understanding Identity in the World of Web APIs – Ronnie Mitra,  API Architec...
Understanding Identity in the World of Web APIs – Ronnie Mitra, API Architec...
 
distributing over the web
distributing over the webdistributing over the web
distributing over the web
 
How APIs Can Be Secured in Mobile Environments
How APIs Can Be Secured in Mobile EnvironmentsHow APIs Can Be Secured in Mobile Environments
How APIs Can Be Secured in Mobile Environments
 
RESTful Web Services
RESTful Web ServicesRESTful Web Services
RESTful Web Services
 
API Workshop: Deep dive into REST APIs
API Workshop: Deep dive into REST APIsAPI Workshop: Deep dive into REST APIs
API Workshop: Deep dive into REST APIs
 
Automating Cloud Operations: Everything You Wanted to Know about cURL and REST
Automating Cloud Operations: Everything You Wanted to Know about cURL and RESTAutomating Cloud Operations: Everything You Wanted to Know about cURL and REST
Automating Cloud Operations: Everything You Wanted to Know about cURL and REST
 
REST API Best Practices & Implementing in Codeigniter
REST API Best Practices & Implementing in CodeigniterREST API Best Practices & Implementing in Codeigniter
REST API Best Practices & Implementing in Codeigniter
 
Understanding and testing restful web services
Understanding and testing restful web servicesUnderstanding and testing restful web services
Understanding and testing restful web services
 
REST in ( a mobile ) peace @ WHYMCA 05-21-2011
REST in ( a mobile ) peace @ WHYMCA 05-21-2011REST in ( a mobile ) peace @ WHYMCA 05-21-2011
REST in ( a mobile ) peace @ WHYMCA 05-21-2011
 
Web Services Tutorial
Web Services TutorialWeb Services Tutorial
Web Services Tutorial
 
Service approach for development Rest API in Symfony2
Service approach for development Rest API in Symfony2Service approach for development Rest API in Symfony2
Service approach for development Rest API in Symfony2
 
Petr Dvořák: Mobilní webové služby pohledem iPhone developera
Petr Dvořák: Mobilní webové služby pohledem iPhone developeraPetr Dvořák: Mobilní webové služby pohledem iPhone developera
Petr Dvořák: Mobilní webové služby pohledem iPhone developera
 
- Webexpo 2010
- Webexpo 2010- Webexpo 2010
- Webexpo 2010
 
Together Cheerfully to Walk with Hypermedia
Together Cheerfully to Walk with HypermediaTogether Cheerfully to Walk with Hypermedia
Together Cheerfully to Walk with Hypermedia
 
Hacking Client Side Insecurities
Hacking Client Side InsecuritiesHacking Client Side Insecurities
Hacking Client Side Insecurities
 
rest-api-basics.pptx
rest-api-basics.pptxrest-api-basics.pptx
rest-api-basics.pptx
 
Crafting APIs
Crafting APIsCrafting APIs
Crafting APIs
 
Web services tutorial
Web services tutorialWeb services tutorial
Web services tutorial
 
Web Services PHP Tutorial
Web Services PHP TutorialWeb Services PHP Tutorial
Web Services PHP Tutorial
 
APIs_ An Introduction.pptx
APIs_ An Introduction.pptxAPIs_ An Introduction.pptx
APIs_ An Introduction.pptx
 

More from OCTO Technology

OCTO TALKS : 4 Tech Trends du Software Engineering.pdf
OCTO TALKS : 4 Tech Trends du Software Engineering.pdfOCTO TALKS : 4 Tech Trends du Software Engineering.pdf
OCTO TALKS : 4 Tech Trends du Software Engineering.pdf
OCTO Technology
 
Le Comptoir OCTO - Équipes infra et prod, ne ratez pas l'embarquement pour l'...
Le Comptoir OCTO - Équipes infra et prod, ne ratez pas l'embarquement pour l'...Le Comptoir OCTO - Équipes infra et prod, ne ratez pas l'embarquement pour l'...
Le Comptoir OCTO - Équipes infra et prod, ne ratez pas l'embarquement pour l'...
OCTO Technology
 
Le Comptoir OCTO - Qu’apporte l’analyse de cycle de vie lors d’un audit d’éco...
Le Comptoir OCTO - Qu’apporte l’analyse de cycle de vie lors d’un audit d’éco...Le Comptoir OCTO - Qu’apporte l’analyse de cycle de vie lors d’un audit d’éco...
Le Comptoir OCTO - Qu’apporte l’analyse de cycle de vie lors d’un audit d’éco...
OCTO Technology
 
Le Comptoir OCTO - Améliorer le Time to Market grâce au Headless : la recette...
Le Comptoir OCTO - Améliorer le Time to Market grâce au Headless : la recette...Le Comptoir OCTO - Améliorer le Time to Market grâce au Headless : la recette...
Le Comptoir OCTO - Améliorer le Time to Market grâce au Headless : la recette...
OCTO Technology
 
Le Comptoir OCTO - Qu'apporte l'analyse de cycle de vie d'un audit d'éco-conc...
Le Comptoir OCTO - Qu'apporte l'analyse de cycle de vie d'un audit d'éco-conc...Le Comptoir OCTO - Qu'apporte l'analyse de cycle de vie d'un audit d'éco-conc...
Le Comptoir OCTO - Qu'apporte l'analyse de cycle de vie d'un audit d'éco-conc...
OCTO Technology
 
Le Comptoir OCTO - Se conformer à la CSRD : un levier d'action insoupçonné
Le Comptoir OCTO - Se conformer à la CSRD : un levier d'action insoupçonnéLe Comptoir OCTO - Se conformer à la CSRD : un levier d'action insoupçonné
Le Comptoir OCTO - Se conformer à la CSRD : un levier d'action insoupçonné
OCTO Technology
 
Le Comptoir OCTO - MLOps : Les patterns MLOps dans le cloud
Le Comptoir OCTO - MLOps : Les patterns MLOps dans le cloudLe Comptoir OCTO - MLOps : Les patterns MLOps dans le cloud
Le Comptoir OCTO - MLOps : Les patterns MLOps dans le cloud
OCTO Technology
 
La Grosse Conf 2024 - Philippe Stepniewski -Atelier - Live coding d'une base ...
La Grosse Conf 2024 - Philippe Stepniewski -Atelier - Live coding d'une base ...La Grosse Conf 2024 - Philippe Stepniewski -Atelier - Live coding d'une base ...
La Grosse Conf 2024 - Philippe Stepniewski -Atelier - Live coding d'une base ...
OCTO Technology
 
La Grosse Conf 2024 - Philippe Prados - Atelier - RAG : au-delà de la démonst...
La Grosse Conf 2024 - Philippe Prados - Atelier - RAG : au-delà de la démonst...La Grosse Conf 2024 - Philippe Prados - Atelier - RAG : au-delà de la démonst...
La Grosse Conf 2024 - Philippe Prados - Atelier - RAG : au-delà de la démonst...
OCTO Technology
 
Le Comptoir OCTO - Maîtriser le RAG : connecter les modèles d’IA génératives ...
Le Comptoir OCTO - Maîtriser le RAG : connecter les modèles d’IA génératives ...Le Comptoir OCTO - Maîtriser le RAG : connecter les modèles d’IA génératives ...
Le Comptoir OCTO - Maîtriser le RAG : connecter les modèles d’IA génératives ...
OCTO Technology
 
OCTO Talks - Les IA s'invitent au chevet des développeurs
OCTO Talks - Les IA s'invitent au chevet des développeursOCTO Talks - Les IA s'invitent au chevet des développeurs
OCTO Talks - Les IA s'invitent au chevet des développeurs
OCTO Technology
 
OCTO Talks - Lancement du livre Culture Test
OCTO Talks - Lancement du livre Culture TestOCTO Talks - Lancement du livre Culture Test
OCTO Talks - Lancement du livre Culture Test
OCTO Technology
 
Le Comptoir OCTO - Green AI, comment éviter que votre votre potion magique d’...
Le Comptoir OCTO - Green AI, comment éviter que votre votre potion magique d’...Le Comptoir OCTO - Green AI, comment éviter que votre votre potion magique d’...
Le Comptoir OCTO - Green AI, comment éviter que votre votre potion magique d’...
OCTO Technology
 
OCTO Talks - State of the art Architecture dans les frontend web
OCTO Talks - State of the art Architecture dans les frontend webOCTO Talks - State of the art Architecture dans les frontend web
OCTO Talks - State of the art Architecture dans les frontend web
OCTO Technology
 
Refcard GraphQL
Refcard GraphQLRefcard GraphQL
Refcard GraphQL
OCTO Technology
 
Comptoir OCTO ALD Automotive/Leaseplan
Comptoir OCTO ALD Automotive/LeaseplanComptoir OCTO ALD Automotive/Leaseplan
Comptoir OCTO ALD Automotive/Leaseplan
OCTO Technology
 
Le Comptoir OCTO - Comment optimiser les stocks en linéaire par la Data ?
Le Comptoir OCTO - Comment optimiser les stocks en linéaire par la Data ? Le Comptoir OCTO - Comment optimiser les stocks en linéaire par la Data ?
Le Comptoir OCTO - Comment optimiser les stocks en linéaire par la Data ?
OCTO Technology
 
Le Comptoir OCTO - Retour sur 5 ans de mise en oeuvre : Comment le RGPD a réi...
Le Comptoir OCTO - Retour sur 5 ans de mise en oeuvre : Comment le RGPD a réi...Le Comptoir OCTO - Retour sur 5 ans de mise en oeuvre : Comment le RGPD a réi...
Le Comptoir OCTO - Retour sur 5 ans de mise en oeuvre : Comment le RGPD a réi...
OCTO Technology
 
Le Comptoir OCTO - Affinez vos forecasts avec la planification distribuée et...
Le Comptoir OCTO -  Affinez vos forecasts avec la planification distribuée et...Le Comptoir OCTO -  Affinez vos forecasts avec la planification distribuée et...
Le Comptoir OCTO - Affinez vos forecasts avec la planification distribuée et...
OCTO Technology
 
Le Comptoir OCTO - La formation au cœur de la stratégie d’éco-conception
Le Comptoir OCTO - La formation au cœur de la stratégie d’éco-conceptionLe Comptoir OCTO - La formation au cœur de la stratégie d’éco-conception
Le Comptoir OCTO - La formation au cœur de la stratégie d’éco-conception
OCTO Technology
 

More from OCTO Technology (20)

OCTO TALKS : 4 Tech Trends du Software Engineering.pdf
OCTO TALKS : 4 Tech Trends du Software Engineering.pdfOCTO TALKS : 4 Tech Trends du Software Engineering.pdf
OCTO TALKS : 4 Tech Trends du Software Engineering.pdf
 
Le Comptoir OCTO - Équipes infra et prod, ne ratez pas l'embarquement pour l'...
Le Comptoir OCTO - Équipes infra et prod, ne ratez pas l'embarquement pour l'...Le Comptoir OCTO - Équipes infra et prod, ne ratez pas l'embarquement pour l'...
Le Comptoir OCTO - Équipes infra et prod, ne ratez pas l'embarquement pour l'...
 
Le Comptoir OCTO - Qu’apporte l’analyse de cycle de vie lors d’un audit d’éco...
Le Comptoir OCTO - Qu’apporte l’analyse de cycle de vie lors d’un audit d’éco...Le Comptoir OCTO - Qu’apporte l’analyse de cycle de vie lors d’un audit d’éco...
Le Comptoir OCTO - Qu’apporte l’analyse de cycle de vie lors d’un audit d’éco...
 
Le Comptoir OCTO - Améliorer le Time to Market grâce au Headless : la recette...
Le Comptoir OCTO - Améliorer le Time to Market grâce au Headless : la recette...Le Comptoir OCTO - Améliorer le Time to Market grâce au Headless : la recette...
Le Comptoir OCTO - Améliorer le Time to Market grâce au Headless : la recette...
 
Le Comptoir OCTO - Qu'apporte l'analyse de cycle de vie d'un audit d'éco-conc...
Le Comptoir OCTO - Qu'apporte l'analyse de cycle de vie d'un audit d'éco-conc...Le Comptoir OCTO - Qu'apporte l'analyse de cycle de vie d'un audit d'éco-conc...
Le Comptoir OCTO - Qu'apporte l'analyse de cycle de vie d'un audit d'éco-conc...
 
Le Comptoir OCTO - Se conformer à la CSRD : un levier d'action insoupçonné
Le Comptoir OCTO - Se conformer à la CSRD : un levier d'action insoupçonnéLe Comptoir OCTO - Se conformer à la CSRD : un levier d'action insoupçonné
Le Comptoir OCTO - Se conformer à la CSRD : un levier d'action insoupçonné
 
Le Comptoir OCTO - MLOps : Les patterns MLOps dans le cloud
Le Comptoir OCTO - MLOps : Les patterns MLOps dans le cloudLe Comptoir OCTO - MLOps : Les patterns MLOps dans le cloud
Le Comptoir OCTO - MLOps : Les patterns MLOps dans le cloud
 
La Grosse Conf 2024 - Philippe Stepniewski -Atelier - Live coding d'une base ...
La Grosse Conf 2024 - Philippe Stepniewski -Atelier - Live coding d'une base ...La Grosse Conf 2024 - Philippe Stepniewski -Atelier - Live coding d'une base ...
La Grosse Conf 2024 - Philippe Stepniewski -Atelier - Live coding d'une base ...
 
La Grosse Conf 2024 - Philippe Prados - Atelier - RAG : au-delà de la démonst...
La Grosse Conf 2024 - Philippe Prados - Atelier - RAG : au-delà de la démonst...La Grosse Conf 2024 - Philippe Prados - Atelier - RAG : au-delà de la démonst...
La Grosse Conf 2024 - Philippe Prados - Atelier - RAG : au-delà de la démonst...
 
Le Comptoir OCTO - Maîtriser le RAG : connecter les modèles d’IA génératives ...
Le Comptoir OCTO - Maîtriser le RAG : connecter les modèles d’IA génératives ...Le Comptoir OCTO - Maîtriser le RAG : connecter les modèles d’IA génératives ...
Le Comptoir OCTO - Maîtriser le RAG : connecter les modèles d’IA génératives ...
 
OCTO Talks - Les IA s'invitent au chevet des développeurs
OCTO Talks - Les IA s'invitent au chevet des développeursOCTO Talks - Les IA s'invitent au chevet des développeurs
OCTO Talks - Les IA s'invitent au chevet des développeurs
 
OCTO Talks - Lancement du livre Culture Test
OCTO Talks - Lancement du livre Culture TestOCTO Talks - Lancement du livre Culture Test
OCTO Talks - Lancement du livre Culture Test
 
Le Comptoir OCTO - Green AI, comment éviter que votre votre potion magique d’...
Le Comptoir OCTO - Green AI, comment éviter que votre votre potion magique d’...Le Comptoir OCTO - Green AI, comment éviter que votre votre potion magique d’...
Le Comptoir OCTO - Green AI, comment éviter que votre votre potion magique d’...
 
OCTO Talks - State of the art Architecture dans les frontend web
OCTO Talks - State of the art Architecture dans les frontend webOCTO Talks - State of the art Architecture dans les frontend web
OCTO Talks - State of the art Architecture dans les frontend web
 
Refcard GraphQL
Refcard GraphQLRefcard GraphQL
Refcard GraphQL
 
Comptoir OCTO ALD Automotive/Leaseplan
Comptoir OCTO ALD Automotive/LeaseplanComptoir OCTO ALD Automotive/Leaseplan
Comptoir OCTO ALD Automotive/Leaseplan
 
Le Comptoir OCTO - Comment optimiser les stocks en linéaire par la Data ?
Le Comptoir OCTO - Comment optimiser les stocks en linéaire par la Data ? Le Comptoir OCTO - Comment optimiser les stocks en linéaire par la Data ?
Le Comptoir OCTO - Comment optimiser les stocks en linéaire par la Data ?
 
Le Comptoir OCTO - Retour sur 5 ans de mise en oeuvre : Comment le RGPD a réi...
Le Comptoir OCTO - Retour sur 5 ans de mise en oeuvre : Comment le RGPD a réi...Le Comptoir OCTO - Retour sur 5 ans de mise en oeuvre : Comment le RGPD a réi...
Le Comptoir OCTO - Retour sur 5 ans de mise en oeuvre : Comment le RGPD a réi...
 
Le Comptoir OCTO - Affinez vos forecasts avec la planification distribuée et...
Le Comptoir OCTO -  Affinez vos forecasts avec la planification distribuée et...Le Comptoir OCTO -  Affinez vos forecasts avec la planification distribuée et...
Le Comptoir OCTO - Affinez vos forecasts avec la planification distribuée et...
 
Le Comptoir OCTO - La formation au cœur de la stratégie d’éco-conception
Le Comptoir OCTO - La formation au cœur de la stratégie d’éco-conceptionLe Comptoir OCTO - La formation au cœur de la stratégie d’éco-conception
Le Comptoir OCTO - La formation au cœur de la stratégie d’éco-conception
 

Recently uploaded

Programming Foundation Models with DSPy - Meetup Slides
Programming Foundation Models with DSPy - Meetup SlidesProgramming Foundation Models with DSPy - Meetup Slides
Programming Foundation Models with DSPy - Meetup Slides
Zilliz
 
Generating privacy-protected synthetic data using Secludy and Milvus
Generating privacy-protected synthetic data using Secludy and MilvusGenerating privacy-protected synthetic data using Secludy and Milvus
Generating privacy-protected synthetic data using Secludy and Milvus
Zilliz
 
UiPath Test Automation using UiPath Test Suite series, part 6
UiPath Test Automation using UiPath Test Suite series, part 6UiPath Test Automation using UiPath Test Suite series, part 6
UiPath Test Automation using UiPath Test Suite series, part 6
DianaGray10
 
Infrastructure Challenges in Scaling RAG with Custom AI models
Infrastructure Challenges in Scaling RAG with Custom AI modelsInfrastructure Challenges in Scaling RAG with Custom AI models
Infrastructure Challenges in Scaling RAG with Custom AI models
Zilliz
 
Uni Systems Copilot event_05062024_C.Vlachos.pdf
Uni Systems Copilot event_05062024_C.Vlachos.pdfUni Systems Copilot event_05062024_C.Vlachos.pdf
Uni Systems Copilot event_05062024_C.Vlachos.pdf
Uni Systems S.M.S.A.
 
Artificial Intelligence for XMLDevelopment
Artificial Intelligence for XMLDevelopmentArtificial Intelligence for XMLDevelopment
Artificial Intelligence for XMLDevelopment
Octavian Nadolu
 
Unlock the Future of Search with MongoDB Atlas_ Vector Search Unleashed.pdf
Unlock the Future of Search with MongoDB Atlas_ Vector Search Unleashed.pdfUnlock the Future of Search with MongoDB Atlas_ Vector Search Unleashed.pdf
Unlock the Future of Search with MongoDB Atlas_ Vector Search Unleashed.pdf
Malak Abu Hammad
 
Climate Impact of Software Testing at Nordic Testing Days
Climate Impact of Software Testing at Nordic Testing DaysClimate Impact of Software Testing at Nordic Testing Days
Climate Impact of Software Testing at Nordic Testing Days
Kari Kakkonen
 
Choosing The Best AWS Service For Your Website + API.pptx
Choosing The Best AWS Service For Your Website + API.pptxChoosing The Best AWS Service For Your Website + API.pptx
Choosing The Best AWS Service For Your Website + API.pptx
Brandon Minnick, MBA
 
Monitoring and Managing Anomaly Detection on OpenShift.pdf
Monitoring and Managing Anomaly Detection on OpenShift.pdfMonitoring and Managing Anomaly Detection on OpenShift.pdf
Monitoring and Managing Anomaly Detection on OpenShift.pdf
Tosin Akinosho
 
Mind map of terminologies used in context of Generative AI
Mind map of terminologies used in context of Generative AIMind map of terminologies used in context of Generative AI
Mind map of terminologies used in context of Generative AI
Kumud Singh
 
HCL Notes and Domino License Cost Reduction in the World of DLAU
HCL Notes and Domino License Cost Reduction in the World of DLAUHCL Notes and Domino License Cost Reduction in the World of DLAU
HCL Notes and Domino License Cost Reduction in the World of DLAU
panagenda
 
“I’m still / I’m still / Chaining from the Block”
“I’m still / I’m still / Chaining from the Block”“I’m still / I’m still / Chaining from the Block”
“I’m still / I’m still / Chaining from the Block”
Claudio Di Ciccio
 
AI 101: An Introduction to the Basics and Impact of Artificial Intelligence
AI 101: An Introduction to the Basics and Impact of Artificial IntelligenceAI 101: An Introduction to the Basics and Impact of Artificial Intelligence
AI 101: An Introduction to the Basics and Impact of Artificial Intelligence
IndexBug
 
Ocean lotus Threat actors project by John Sitima 2024 (1).pptx
Ocean lotus Threat actors project by John Sitima 2024 (1).pptxOcean lotus Threat actors project by John Sitima 2024 (1).pptx
Ocean lotus Threat actors project by John Sitima 2024 (1).pptx
SitimaJohn
 
Driving Business Innovation: Latest Generative AI Advancements & Success Story
Driving Business Innovation: Latest Generative AI Advancements & Success StoryDriving Business Innovation: Latest Generative AI Advancements & Success Story
Driving Business Innovation: Latest Generative AI Advancements & Success Story
Safe Software
 
UI5 Controls simplified - UI5con2024 presentation
UI5 Controls simplified - UI5con2024 presentationUI5 Controls simplified - UI5con2024 presentation
UI5 Controls simplified - UI5con2024 presentation
Wouter Lemaire
 
Taking AI to the Next Level in Manufacturing.pdf
Taking AI to the Next Level in Manufacturing.pdfTaking AI to the Next Level in Manufacturing.pdf
Taking AI to the Next Level in Manufacturing.pdf
ssuserfac0301
 
Fueling AI with Great Data with Airbyte Webinar
Fueling AI with Great Data with Airbyte WebinarFueling AI with Great Data with Airbyte Webinar
Fueling AI with Great Data with Airbyte Webinar
Zilliz
 
Building Production Ready Search Pipelines with Spark and Milvus
Building Production Ready Search Pipelines with Spark and MilvusBuilding Production Ready Search Pipelines with Spark and Milvus
Building Production Ready Search Pipelines with Spark and Milvus
Zilliz
 

Recently uploaded (20)

Programming Foundation Models with DSPy - Meetup Slides
Programming Foundation Models with DSPy - Meetup SlidesProgramming Foundation Models with DSPy - Meetup Slides
Programming Foundation Models with DSPy - Meetup Slides
 
Generating privacy-protected synthetic data using Secludy and Milvus
Generating privacy-protected synthetic data using Secludy and MilvusGenerating privacy-protected synthetic data using Secludy and Milvus
Generating privacy-protected synthetic data using Secludy and Milvus
 
UiPath Test Automation using UiPath Test Suite series, part 6
UiPath Test Automation using UiPath Test Suite series, part 6UiPath Test Automation using UiPath Test Suite series, part 6
UiPath Test Automation using UiPath Test Suite series, part 6
 
Infrastructure Challenges in Scaling RAG with Custom AI models
Infrastructure Challenges in Scaling RAG with Custom AI modelsInfrastructure Challenges in Scaling RAG with Custom AI models
Infrastructure Challenges in Scaling RAG with Custom AI models
 
Uni Systems Copilot event_05062024_C.Vlachos.pdf
Uni Systems Copilot event_05062024_C.Vlachos.pdfUni Systems Copilot event_05062024_C.Vlachos.pdf
Uni Systems Copilot event_05062024_C.Vlachos.pdf
 
Artificial Intelligence for XMLDevelopment
Artificial Intelligence for XMLDevelopmentArtificial Intelligence for XMLDevelopment
Artificial Intelligence for XMLDevelopment
 
Unlock the Future of Search with MongoDB Atlas_ Vector Search Unleashed.pdf
Unlock the Future of Search with MongoDB Atlas_ Vector Search Unleashed.pdfUnlock the Future of Search with MongoDB Atlas_ Vector Search Unleashed.pdf
Unlock the Future of Search with MongoDB Atlas_ Vector Search Unleashed.pdf
 
Climate Impact of Software Testing at Nordic Testing Days
Climate Impact of Software Testing at Nordic Testing DaysClimate Impact of Software Testing at Nordic Testing Days
Climate Impact of Software Testing at Nordic Testing Days
 
Choosing The Best AWS Service For Your Website + API.pptx
Choosing The Best AWS Service For Your Website + API.pptxChoosing The Best AWS Service For Your Website + API.pptx
Choosing The Best AWS Service For Your Website + API.pptx
 
Monitoring and Managing Anomaly Detection on OpenShift.pdf
Monitoring and Managing Anomaly Detection on OpenShift.pdfMonitoring and Managing Anomaly Detection on OpenShift.pdf
Monitoring and Managing Anomaly Detection on OpenShift.pdf
 
Mind map of terminologies used in context of Generative AI
Mind map of terminologies used in context of Generative AIMind map of terminologies used in context of Generative AI
Mind map of terminologies used in context of Generative AI
 
HCL Notes and Domino License Cost Reduction in the World of DLAU
HCL Notes and Domino License Cost Reduction in the World of DLAUHCL Notes and Domino License Cost Reduction in the World of DLAU
HCL Notes and Domino License Cost Reduction in the World of DLAU
 
“I’m still / I’m still / Chaining from the Block”
“I’m still / I’m still / Chaining from the Block”“I’m still / I’m still / Chaining from the Block”
“I’m still / I’m still / Chaining from the Block”
 
AI 101: An Introduction to the Basics and Impact of Artificial Intelligence
AI 101: An Introduction to the Basics and Impact of Artificial IntelligenceAI 101: An Introduction to the Basics and Impact of Artificial Intelligence
AI 101: An Introduction to the Basics and Impact of Artificial Intelligence
 
Ocean lotus Threat actors project by John Sitima 2024 (1).pptx
Ocean lotus Threat actors project by John Sitima 2024 (1).pptxOcean lotus Threat actors project by John Sitima 2024 (1).pptx
Ocean lotus Threat actors project by John Sitima 2024 (1).pptx
 
Driving Business Innovation: Latest Generative AI Advancements & Success Story
Driving Business Innovation: Latest Generative AI Advancements & Success StoryDriving Business Innovation: Latest Generative AI Advancements & Success Story
Driving Business Innovation: Latest Generative AI Advancements & Success Story
 
UI5 Controls simplified - UI5con2024 presentation
UI5 Controls simplified - UI5con2024 presentationUI5 Controls simplified - UI5con2024 presentation
UI5 Controls simplified - UI5con2024 presentation
 
Taking AI to the Next Level in Manufacturing.pdf
Taking AI to the Next Level in Manufacturing.pdfTaking AI to the Next Level in Manufacturing.pdf
Taking AI to the Next Level in Manufacturing.pdf
 
Fueling AI with Great Data with Airbyte Webinar
Fueling AI with Great Data with Airbyte WebinarFueling AI with Great Data with Airbyte Webinar
Fueling AI with Great Data with Airbyte Webinar
 
Building Production Ready Search Pipelines with Spark and Milvus
Building Production Ready Search Pipelines with Spark and MilvusBuilding Production Ready Search Pipelines with Spark and Milvus
Building Production Ready Search Pipelines with Spark and Milvus
 

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.