RESTful webservices: yesterday, today, tomorrow. Lemberg's presentation for Lviv Euro Drupal Camp 2013. For more articles visit blog.lemberg.co.uk

1. 1

2. 


This presentation is not about Drupal
It’s probably a bit boring: no funny
images, no code listings and a lot of text
Still here? Let’s go!
2

3. 




Brief web APIs history overview
What is web API
What is REST
How to design great web APIs
What does Drupal offer for web APIs
3

4. Web API is a bridge between your application
and the rest of the world
4

5. 5

6. 6

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

8. 1.
2.
3.
4.
5.
6.
Write documentation
Reuse functionality of HTTP protocol
Be pragmatic
Be consistent
Be simple, hide complexity
Do not invent custom authorization method
8

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

10. 



/getCat
/createCat
/getAllClients
/newVehicleCustomer




/cats
/clients
/customers
/vehicles
10

11. 

Verbs are okay:
/convert?from=UAH&to=USD&amount=100
Define this “non-resource” behavior explicitly
11

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

20. 1.
2.
3.
4.
5.
Services (6.x; 7.x):
https://drupal.org/project/services
RESTful Web Services (7.x):
https://drupal.org/project/restws
Services Entity API (7.x)
http://drupal.org/project/services_entity
REST services (7.x)
https://drupal.org/sandbox/Taran2L/18073
78
REST in core (8.x)
20

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

23. 

Combines approaches from Services and
RESTWS
Configurable endpoints + Entity API for data
management
23

24. ?
24

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

27. Thank you!
27