7. Is an architectural style, not a strict standard
Offers a lot of flexibility
Allows to design best practices
Provides interfaces that developers love
7
9.
Use single access point, i.e. api.example.com
There should be only 2 base URLs per
resource:
/cats
/cats/16
Be consistent: use either singular or plural
nouns
Avoid extra abstraction, use concrete names,
avoid /items, /assets etc
9
12. There are plenty of HTTP methods: GET, POST, PUT, DELETE, PATCH,
OPTIONS, HEAD etc
There are 4 basic operations: Create, Read, Update, Delete (CRUD)
POST => Create, GET => Read, PUT => Update, DELETE => Delete
Resource
POST
/cats
/cats/123
GET
PUT
DELETE
Create a new List cats
cat
Bulk update
cats
Delete all
cats
-
If exists,
update cat
Delete cat
Show cat
12
13.
Deep URLs structure is a bad practice, i.e.
avoid long URLs:
/client/1/application/2/version/3/terms
Use simple approach:
/resource/identifier/resource
13
14.
Keep base URLs structure simple
Hide all extra information behind the “?”:
◦
◦
◦
◦
Pagination
Search
Collection filtering
Partial response
14
15.
Use HTTP status codes
Make error messages as verbose as possible
Use Warning header for any extra information
Provide debug mode (hide under the “?”)
Allow for suppressing this behavior (hide
under the “?”):
/cats?suppress_http_errors=true
15
16.
API version number is mandatory
Use a simple ordinal number, i.e. v1, v2
Maintain at least two versions: current and
the previous one
Put version in the base URL or in the header
16
17.
All requests should use pagination
Define defaults: number of records and offset
Define pagination: limit & offset
/cats?limit=10&offset=0
Use the same limit and offset for all resources
Allow for a partial response. Hide fields
filtering behind the “?”
/cats?fields=name,color,weight
17
18.
Respect Accept header
Throw an error, if you cannot deliver
response in the expected format (406 Not
Acceptable)
Use JSON as a default format
18
19. That’s it.
Do not invent custom authorization.
Do not use oAuth-like authorization.
19
21.
Relies on the endpoints (custom URLs)
Uses drupal_form_submit() for write
operations
Out of the box covers nodes, comments,
users only
No default Drupal cookie based
authentication (requires explicit
authentication with custom hooks)
Great integration with other modules (like
Views)
21
22.
Relies on Entity API and metadata about
entities
No endpoints: uses /entity_type/1.json or
/entity_type/1.xml
Supports any entity type out of the box
Access control on top of Entity API and Field
API
Standard user authentication over session
cookies or HTTP Basic Auth submodule
22
25.
Hypertext Transfer Protocol -- HTTP/1.1
http://tools.ietf.org/html/rfc2616
Web API Design
http://apigee.com/about/content/web-apidesign
REST and Serialization in Drupal 8
http://linclark.github.io/d8-rest-slides/
http://www.youtube.com/watch?v=w6dqzDb
Y78k
25
26. Head of Web development @ Lemberg Solutions
Taran2L
https://drupal.org/user/473438
Roman Paska
http://linkedin.com/in/romanpaska/
26
