Create a RESTful apiNovember 15, 2012

AmsterdamPHP

AmsterdamPHP

INTRODUCTION

AmsterdamPHP

Marc Ypes@Ceeram

CakePHP 4 yearsCore team 1.5 years

Undercover as programmer

OVERVIEW

AmsterdamPHP

■ Content-types■ Interface■ Authentication■ Cache■ Errors

INTRODUCTION TO REST

AmsterdamPHP

Representational state transfer

Set of architectural principles

- resource focussed- manipulation through representations- HTTP protocol?

INTRODUCTION TO REST

AmsterdamPHP

Constraints

■ Client-server■ Stateless■ Uniform interface■ Cacheable■ Layered system

INTRODUCTION TO REST

AmsterdamPHP

Client-server

separation of concerns

portability of UI across platforms, scalability

allowing components to evolve independently

INTRODUCTION TO REST

AmsterdamPHP

Stateless

request includes required information

no stored context on server: Sessions

INTRODUCTION TO REST

AmsterdamPHP

Uniform interface

information is transfered in standardized form

using nouns for resources

(http) protocol describes methods

INTRODUCTION TO REST

AmsterdamPHP

Cacheable

reducing latency

lower serverload

INTRODUCTION TO REST

AmsterdamPHP

Layered system

ServerClient

ProxyGatewaySecurityAnything

INTRODUCTION TO REST

AmsterdamPHP

Uniform interface

■ resource

■ identification of the resource

■ manipulation through representation

■ self-descriptive

■ hypermedia as the engine of application state HATEOAS

INTRODUCTION TO REST

AmsterdamPHP

Uniform Interface

Data element Exampleresource user, book etc. (users, books etc.)resource identifier URL, URN (/users/1234)representation

data TXT / HTML / XML /YAML,JSONmetadata content type, last-modified time

resource metadata source link, alternatecontrol data if-modified-since, cache-control, etag

http://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arch_style.htm

INTRODUCTION TO REST

AmsterdamPHP

Uniform Interface

/api/getUserProfile/1234

/api/users?action=vote&id=1234

/api/deleteUser?id=1

INTRODUCTION TO REST

AmsterdamPHP

Uniform Interface

RPC style

Steep learning curveDocumentationNew functionality, BC

INTRODUCTION TO REST

AmsterdamPHP

Uniform Interface

2 base urls

- /books- /books/1234

INTRODUCTION TO REST

AmsterdamPHP

Uniform Interface

GET /users Get collectionPOST /users Add to collectionGET /users/1234 Get resourcePUT /users/1234 Update resourceDELETE /users/1234 Delete resource

Update is not replace?POST /users/1234

INTRODUCTION TO REST

AmsterdamPHP

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

INTRODUCTION TO REST

AmsterdamPHP

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":{........"}}

INTRODUCTION TO REST

AmsterdamPHP

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

INTRODUCTION TO REST

AmsterdamPHP

Uniform Interface

Safe methodsIdempotent methods

GET (HEAD) is safe (nullipotent)PUT, DELETE are idempotent

POSTPATCH?

INTRODUCTION TO REST

AmsterdamPHP

Uniform Interface

Normalize the resources

GET /books/1849511926/votes

GET /votes?book=1849511926

INTRODUCTION TO REST

AmsterdamPHP

Uniform Interface

Normalize the resources

POST /books/1849511926/votes

PUT /books/1849511926data contains votes subresource data

POST /votesdata is book=1849511926

INTRODUCTION TO REST

AmsterdamPHP

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/

INTRODUCTION TO REST

AmsterdamPHP

Versioning

/rest/v1

content-type

INTRODUCTION TO REST

AmsterdamPHP

Uniform Interface / HATEOAS

Level 3 of REST maturity model (RMM)

INTRODUCTION TO REST

AmsterdamPHP

Uniform Interface / HATEOAS

Level 0

Single URI, single HTTP method

INTRODUCTION TO REST

AmsterdamPHP

Uniform Interface / HATEOAS

Level 1

Many URI, single HTTP method

INTRODUCTION TO REST

AmsterdamPHP

Uniform Interface / HATEOAS

Level 2

Many URI, different HTTP methods

INTRODUCTION TO REST

AmsterdamPHP

Uniform Interface / HATEOAS

Level 3

Self descriptive■ Media types■ Links■ Other protocols

INTRODUCTION TO REST

AmsterdamPHP

Uniform Interface / HATEOAS

HATEOAS

GET /comments?book=1849511926

Link to api.amazin.com/books/1849511926

Links to all comments

INTRODUCTION TO REST

AmsterdamPHP

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>

INTRODUCTION TO REST

AmsterdamPHP

Uniform Interface / HATEOAS{

"foo":"great book","book":

{"links":[

{"href":"/books/1849511926", "title":"wow"

}]

}}

INTRODUCTION TO REST

AmsterdamPHP

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

INTRODUCTION TO REST

AmsterdamPHP

Uniform Interface / Errors

HTTP Statuscodes

Human reads messageCode reads code

INTRODUCTION TO REST

AmsterdamPHP

Uniform Interface / Errors

HTTP Statuscodes

200 OK201 Created204 No Content304 Not Modified400 Bad Request401 Unauthorized404 Not Found405 Method Not Allowed

INTRODUCTION TO REST

AmsterdamPHP

Uniform Interface / Errors

Link to support page

Link: <http://api.amazin.com/errors/405>; rel="help"

REST my Cake

CakeFest 2012 Manchester

Authentication

PublicApi-keyBasic AuthOAuth

INTRODUCTION TO REST

AmsterdamPHP

Cacheable

HTTP Cache headers

Use them!

INTRODUCTION TO REST

AmsterdamPHP

Cacheable

HTTP Cache headers

Cache-control- private- public- max-age / s-maxage- must-revalidate- nocache

INTRODUCTION TO REST

AmsterdamPHP

Cacheable

HTTP Cache validation

Etag ResponseLast-Modified Response

If-Modified-Since Request (GET)If-None-Match Request (GET)

If-Match Request (PUT)

REST my Cake

AmsterdamPHP

CakeResponse

header( $header = NULL, $value = NULL )send( )statusCode( $code = NULL )type( $contentType = NULL )

REST my Cake

AmsterdamPHP

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 )

REST my Cake

AmsterdamPHP

CakePHP 3.0

2013PHP 5.4composerarrays => objects

INTRODUCTION TO REST

AmsterdamPHP

REST might not be what you are looking for

Questions?

INTRODUCTION TO REST

AmsterdamPHP

THANKS

https://joind.in/event/view/1141