Cake fest 2012 create a restful api

CakeFest 2012

Create a RESTful api
Sept 1, 2012
CakeFest 2012 Manchester

INTRODUCTION

Marc Ypes
@Ceeram

CakePHP 4 years
Core team 1.5 years
Undercover as programmer


OVERVIEW

REST my case?
REST your Cake

■ Content-type
■ Routing
■ Interface
■ Authentication
■ Cache
■ Errors


INTRODUCTION TO REST
Representational state transfer

Set of architectural principles

- resource focussed
- manipulation through representations
- HTTP protocol?


Constraints

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


Uniform interface

■ resource

■ identification of the resource

■ manipulation through representation

■ self-descriptive

■ hypermedia as the engine of application state
HATEOAS

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


Uniform Interface

/api/getUserProfile/1234
/api/addVoteForUser?id=1234
/api/users?action=vote&id=1234
/api/deleteUser/1
/api/deleteUser?id=1
/api/favoritedUsers
/api/getUserData/1?fields=name,email


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 update?
POST /users/1234


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


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

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


Uniform Interface

Safe methods
Idempotent methods

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

POST
PATCH?


Uniform Interface

Normalize the resources

GET /books/1849511926/votes

GET /votes?book=1849511926


Uniform Interface

Normalize the resources

POST /books/1849511926/votes

PUT /books/1849511926
data contains votes subresource data

POST /votes
data is book=1849511926


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/


Uniform Interface / HATEOAS

Level 3 of REST maturity model (RMM)



Level 0

Single URI, single HTTP method



Level 1

Many URI, single HTTP method



Level 2

Many URI, different HTTP methods



Level 3

Self descriptive
■ Media types
■ Links
■ Other protocols



HATEOAS

GET /comments?book=1849511926

Link to api.amazin.com/books/1849511926

Links to all comments


>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>
</vote>

{
"foo":"bar",
"book":
{
"links":[
{
"href":"/book/1849511926",
"title":"wow"
}
]
}
}


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

Uniform Interface / Errors

HTTP Statuscodes

Human reads message
Code reads code



HTTP Statuscodes

200 OK
201 Created
204 No Content
304 Not Modified
400 Bad Request
401 Unauthorized
404 Not Found
405 Method Not Allowed


Link to support page

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


Cacheable

HTTP Cache headers

Use them!


Cacheable

HTTP Cache headers

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


Cacheable

HTTP Cache validation

Etag RS
Last-Modified RS

If-Modified-Since RQ
If-None-Match RQ

If-Match RQ



REST might not be what you are looking for

Questions?

Rest my Cake


REST my Cake
Basic setup

Route urls with extensions
http://localhost/cats/index.json

app/Config/routes.php
<?php
// allow any url extension
Router::parseExtensions();

//or allow .json extension only
Router::parseExtensions('json');


REST my Cake
Basic setup

Add RequestHandler component
<?php
App::uses('Controller', 'Controller');

class AppController extends Controller {

public $components = array(
'DebugKit.Toolbar',
'Session',
'RequestHandler',
);
}


REST my Cake
Basic setup

Create view files, the CakePHP 1.3 way (almost)

app/View/Cats/json/index.ctp

<?php echo json_encode($cats) ;?>


REST my Cake
Basic setup

Use auto serialization, the CakePHP 2.x way

public function view($id = null) {
$this->Cat->id = $id;
if (!$this->Cat->exists()) {
throw new NotFoundException(__('Invalid cat'));
}
$this->set('cat', $this->Cat->read(null, $id));
$this->set('_serialize', array('cat'));
}

REST my Cake
http://localhost/cats/index.json


REST my Cake
http://localhost/cats/view/1.json


REST my Cake
REST Routing

Resource mapping

http://localhost/cats
http://localhost/cats/1


Router::mapResources(array('Cats', 'Users'));


REST my Cake
REST Routing

Resource mapping

GET /cats index()
POST /cats add()
GET /cats/1 view(1)
POST /cats/1 edit(1)
PUT /cats/1 edit(1)
DELETE /cats/1 delete(1)


REST my Cake
REST Routing

Resource mapping

X-HTTP-Method-Override
<Limit PUT DELETE>
order deny,allow
allow from all
</Limit>


REST my Cake
REST Routing

Resource mapping
Router::resourceMap(array(
array('action' => 'index','method' => 'GET','id' => false),
array('action' => 'read','method' => 'GET','id' => true),
array('action' => 'add','method' => 'POST','id' => false),
array('action' => 'edit','method' => 'POST','id' => true),
array('action' => 'replace','method' => 'PUT','id' => true),
array('action' => 'update','method' => 'PATCH','id' => true),
array('action' => 'delete','method' => 'DELETE','id' => true)
array('action' => 'truncate','method'=>'DELETE','id'=>false)
));

REST my Cake
REST Routing

Resource mapping
Router::mapResources(
array('Cats', 'Users', 'Pizza.Orders')
);

/cats => CatsController::index() in app
/users => UsersController::index() in app
/pizza/orders => OrdersController::index() in Pizza plugin

REST my Cake
REST Routing

Resource mapping
array('Cats', 'Users', 'Pizza.Orders'),
array('prefix' => '/api/')
);

/api/cats => CatsController::index() in app
/api/users => UsersController::index() in app
/api/orders => OrdersController::index() in Pizza plugin

REST my Cake
REST Routing

Resource mapping
array('Cats', 'Users', 'Pizza.Orders'),
array('prefix' => '/api/, 'id' => Router::UUID')
);

/api/cats => CatsController::index() in app
/api/users => UsersController::index() in app
/api/orders => OrdersController::index() in Pizza plugin

REST my Cake
REST Routing

.json
?format=json

curl -H "Accept: application/json" http://localhost/cats


REST my Cake
REST Routing

GET /cats/sleeping
GET /cats?status=sleeping
GET /cats?sleeping=1

GET /posts/recent
GET /posts?type=recent


REST my Cake
REST Routing

/posts/foo/bar routes with passed params
/posts/foo:bar routes with named params
Router::connect('/api/cats/*',
array(
'plugin' => null,
'controller' => 'posts',
'action' => 'index',
'[method]' => 'GET'
));

REST my Cake
REST Routing

GET /users/vote/1234
POST /users/vote/1234 $this->Html->postLink()
POST /api/users/1234/votes
public function vote($id = null) {
//user id exist, httpmethod checks etc.
$this->User->updateAll(
array('User.votes' => 'User.votes + 1'),
array('User.id' => $id)
);
}

REST my Cake
REST Routing

POST /users/1234/votes
Router::connect('/api/users/:id/votes',
array(
'plugin' => null,
'controller' => 'users',
'action' => 'vote',
'[method]' => 'POST'
),
array('id' => Router::ID, 'pass' => 'id')
);

REST my Cake
REST Routing

POST /users/1234/votes
public function vote($id = null) {
//user id exist checks etc
$this->User->Vote->add($id);
}
POST /votes
public function add() {
$this->Vote->add($this->request->data['Vote.
user']);
}


REST my Cake
REST Routing

CakeRequest::addDetector(
'patch',
array(
'env' => 'REQUEST_METHOD',
'value' => 'PATCH'
));


REST my Cake
CakeResponse

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


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 )

REST my Cake
RequestHandlerComponent

public $components = array(
'RequestHandler' => array(
'viewClassMap' => array(
'json' => 'RestJson',
'xml' => 'RestXml'
)
)
);

REST my Cake
Authentication

Public
Api-key
Basic Auth
OAuth


REST my Cake
Authentication

public function getUser(CakeRequest $request) {
if (!empty($this->settings['header'])) {
$token = $request->header($this->settings['header']);
if ($token) {
return $this->_findUser($token, null);
}
}
if (!empty($request->query[$this->settings['parameter']])) {
$token = $request->query[$this->settings['parameter']];
return $this->_findUser($token);
}
return false;
}


REST my Cake
Versioning

/rest
/v1


REST my Cake

THANKS


Cake fest 2012 create a restful api

Recommandé

Recommandé

Contenu connexe

Tendances

Tendances (20)

Similaire à Cake fest 2012 create a restful api

Similaire à Cake fest 2012 create a restful api (20)

Dernier

Dernier (20)

Cake fest 2012 create a restful api