1. AmsterdamPHP
Create a RESTful api
November 15, 2012
AmsterdamPHP

2. INTRODUCTION
Marc Ypes
@Ceeram
CakePHP 4 years
Core team 1.5 years
Undercover as programmer
AmsterdamPHP

3. OVERVIEW
■ Content-types
■ Interface
■ Authentication
■ Cache
■ Errors
AmsterdamPHP

4. INTRODUCTION TO REST
Representational state transfer
Set of architectural principles
- resource focussed
- manipulation through representations
- HTTP protocol?
AmsterdamPHP

5. INTRODUCTION TO REST
Constraints
■ Client-server
■ Stateless
■ Uniform interface
■ Cacheable
■ Layered system
AmsterdamPHP

6. INTRODUCTION TO REST
Client-server
separation of concerns
portability of UI across platforms, scalability
allowing components to evolve independently
AmsterdamPHP

7. INTRODUCTION TO REST
Stateless
request includes required information
no stored context on server: Sessions
AmsterdamPHP

8. INTRODUCTION TO REST
Uniform interface
information is transfered in standardized form
using nouns for resources
(http) protocol describes methods
AmsterdamPHP

9. INTRODUCTION TO REST
Cacheable
reducing latency
lower serverload
AmsterdamPHP

10. INTRODUCTION TO REST
Layered system
Server
Client
Proxy
Gateway
Security
Anything
AmsterdamPHP

11. INTRODUCTION TO REST
Uniform interface
■ resource
■ identification of the resource
■ manipulation through representation
■ self-descriptive
■ hypermedia as the engine of application state
HATEOAS
AmsterdamPHP

12. INTRODUCTION TO REST
Uniform Interface
Data element Example
resource user, book etc. (users, books etc.)
resource identifier URL, URN (/users/1234)
representation
data TXT / HTML / XML /YAML,JSON
metadata content type, last-modified time
resource metadata source link, alternate
control data if-modified-since, cache-control, etag
http://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arch_style.htm
AmsterdamPHP

13. INTRODUCTION TO REST
Uniform Interface
/api/getUserProfile/1234
/api/users?action=vote&id=1234
/api/deleteUser?id=1
AmsterdamPHP

14. INTRODUCTION TO REST
Uniform Interface
RPC style
Steep learning curve
Documentation
New functionality, BC
AmsterdamPHP

15. INTRODUCTION TO REST
Uniform Interface
2 base urls
- /books
- /books/1234
AmsterdamPHP

16. INTRODUCTION TO REST
Uniform Interface
GET /users Get collection
POST /users Add to collection
GET /users/1234 Get resource
PUT /users/1234 Update resource
DELETE /users/1234 Delete resource
Update is not replace?
POST /users/1234
AmsterdamPHP

17. INTRODUCTION TO REST
Uniform Interface
Typical request:
>GET /books/1849511926 HTTP/1.1
>Host: api.amazin.com
>Accept: application/json
>If-Modified-Since: Sat, 01 Sep 2012 10:22:36 GMT
AmsterdamPHP

18. INTRODUCTION TO REST
Uniform Interface
Typical response:
< HTTP/1.1 200 OK
< Date: Sat, 01 Sep 2012 11:45:12 GMT
< Server: Apache/2.2.16 (Debian)
< Last-Modified: Sat, 01 Sep 2012 11:25:31 GMT
< Content-Length: 145
< Content-Type: application/json
{"book":{........"}}
AmsterdamPHP

19. INTRODUCTION TO REST
Uniform Interface
Typical response:
< HTTP/1.1 304 Not Modified
< Date: Sat, 01 Sep 2012 11:45:12 GMT
< Server: Apache/2.2.16 (Debian)
< Vary: Accept-Encoding
AmsterdamPHP

20. INTRODUCTION TO REST
Uniform Interface
Safe methods
Idempotent methods
GET (HEAD) is safe (nullipotent)
PUT, DELETE are idempotent
POST
PATCH?
AmsterdamPHP

21. INTRODUCTION TO REST
Uniform Interface
Normalize the resources
GET /books/1849511926/votes
GET /votes?book=1849511926
AmsterdamPHP

22. INTRODUCTION TO REST
Uniform Interface
Normalize the resources
POST /books/1849511926/votes
PUT /books/1849511926
data contains votes subresource data
POST /votes
data is book=1849511926
AmsterdamPHP

23. INTRODUCTION TO REST
Uniform Interface
PATCH
Edge Rails: PATCH is the new primary HTTP method for updates
http://weblog.rubyonrails.org/2012/2/25/edge-rails-patch-is-the-new-primary-http-method-for-updates/
AmsterdamPHP

24. INTRODUCTION TO REST
Versioning
/rest
/v1
content-type
AmsterdamPHP

25. INTRODUCTION TO REST
Uniform Interface / HATEOAS
Level 3 of REST maturity model (RMM)
AmsterdamPHP

26. INTRODUCTION TO REST
Uniform Interface / HATEOAS
Level 0
Single URI, single HTTP method
AmsterdamPHP

27. INTRODUCTION TO REST
Uniform Interface / HATEOAS
Level 1
Many URI, single HTTP method
AmsterdamPHP

28. INTRODUCTION TO REST
Uniform Interface / HATEOAS
Level 2
Many URI, different HTTP methods
AmsterdamPHP

29. INTRODUCTION TO REST
Uniform Interface / HATEOAS
Level 3
Self descriptive
■ Media types
■ Links
■ Other protocols
AmsterdamPHP

30. INTRODUCTION TO REST
Uniform Interface / HATEOAS
HATEOAS
GET /comments?book=1849511926
Link to api.amazin.com/books/1849511926
Links to all comments
AmsterdamPHP

31. INTRODUCTION TO REST
Uniform Interface / HATEOAS
>GET /comments/1
<HTTP/1.1 200 Ok
<Content-Type: text/xml
<?xml version="1.0">
<comment>
<foo>great book</foo>
<book>
<link href="/books/1849511926" title="wow" />
</book>
</comment>
AmsterdamPHP

32. INTRODUCTION TO REST
Uniform Interface / HATEOAS
{
"foo":"great book",
"book":
{
"links":[
{
"href":"/books/1849511926",
"title":"wow"
}
]
}
}
AmsterdamPHP

33. INTRODUCTION TO REST
Uniform Interface / HATEOAS
Link header
Link: <https://api.github.com/user/repos?page=2&per_page=100>;rel="
next",
<https://api.github.com/user/repos?page=50&per_page=100>;rel="last"
github.com
AmsterdamPHP

34. INTRODUCTION TO REST
Uniform Interface / Errors
HTTP Statuscodes
Human reads message
Code reads code
AmsterdamPHP

35. INTRODUCTION TO REST
Uniform Interface / Errors
HTTP Statuscodes
200 OK
201 Created
204 No Content
304 Not Modified
400 Bad Request
401 Unauthorized
404 Not Found
405 Method Not Allowed
AmsterdamPHP

36. INTRODUCTION TO REST
Uniform Interface / Errors
Link to support page
Link: <http://api.amazin.com/errors/405>; rel="help"
AmsterdamPHP

37. REST my Cake
Authentication
Public
Api-key
Basic Auth
OAuth
CakeFest 2012 Manchester

38. INTRODUCTION TO REST
Cacheable
HTTP Cache headers
Use them!
AmsterdamPHP

39. INTRODUCTION TO REST
Cacheable
HTTP Cache headers
Cache-control
- private
- public
- max-age / s-maxage
- must-revalidate
- nocache
AmsterdamPHP

40. INTRODUCTION TO REST
Cacheable
HTTP Cache validation
Etag Response
Last-Modified Response
If-Modified-Since Request (GET)
If-None-Match Request (GET)
If-Match Request (PUT)
AmsterdamPHP

41. REST my Cake
CakeResponse
header( $header = NULL, $value = NULL )
send( )
statusCode( $code = NULL )
type( $contentType = NULL )
AmsterdamPHP

42. REST my Cake
CakeResponse
cache( $since, $time = '+1 day' )
checkNotModified( $request )
disableCache( )
etag( $tag = NULL, $weak = false )
expires( $time = NULL )
maxAge( $seconds = NULL )
modified( $time = NULL )
mustRevalidate( $enable = NULL )
notModified( )
sharable( $public = NULL, $time = NULL )
sharedMaxAge( $seconds = NULL )
AmsterdamPHP

43. REST my Cake
CakePHP 3.0
2013
PHP 5.4
composer
arrays => objects
AmsterdamPHP

44. INTRODUCTION TO REST
REST might not be what you are looking for
Questions?
AmsterdamPHP

45. INTRODUCTION TO REST
THANKS
https://joind.in/event/view/1141
AmsterdamPHP