Rest api titouan benoit

RESTful API
Titouan BENOIT – CTO at Welp.fr
titouan.benoit@gmx.fr

RESTful API – Titouan BENOIT
Titouan BENOIT – CTO at Welp
– titouan@welp.today
– titouan.benoit@gmx.fr
RESTful API - v1.0 2
Titouan BENOIT

Plan
7. Tools
– CURL
– Postman
8. Examples
9. Development
– Laravel
– Symfony2
• FosRestBundle
• NelmioApiDoc
10. CORS
– NelmioCors
1. Introduction
2. RESTful API
3. HTTP(S) Request
4. Response
– JSON
– XML
5. Authentification
– Basic Auth
– OAuth2
6. Guidelines

A Web service is a service offered by an electronic device to another one,
communicating with each other via the World wide web
– 2002: W3C Web Services Architecture Working Group
• SOAP (Simple Object Access Protocol)
• HTTP
• XML Serialization
– 2004: two major classes of Web services:
• REST-compliant Web services
• Arbitrary Web services
A software system designed to support interoperable machine-to-
machine interaction over a network
1. Introduction

Representational State Transfer (REST)
– Software architectural style
– Communicate over (not always) HTTP(S)
– With HTTP verbs (GET, POST, PUT, DELETE, etc.)
– Web resources identified by Uniform Resource Identifiers (URIs)
– CRUD (Create, Read, Update, Delete)
– Examples:
• GET http://myapi.domain.com/resources/2
• DELETE http://myapi.domain.com/resources/3
• GET http://myapi.domain.com/resources
REST was defined by Roy Thomas Fielding in his 2000 PhD dissertation "Architectural Styles and the
Design of Network-based Software Architectures"
2. RESTful API

RESTFUL API
3. HTTP(S) Request
8

3. HTTP(S) Request
HTTP Verbs URI Action Description
GET api/resources getResourcesAction Retrieve all resources
GET api/resources/2 getResourceAction(id) Retrieve resource id 2
POST api/resources postResourcesAction(Request) Create a new resource
PATCH api/resources/1 patchResourcesAction(Request,id) Edit resource id 1
PUT api/resources/1 putResourcesAction(Request,id) Edit resource id 1
DELETE api/resources/3 deleteResourcesAction(id) Delete resource id 3

3. HTTP(S) Request - Filters
Filters
– Filters and sorting on resources
• https://api.example.com/resources?filters=type1&sort=asc
– Only use URL parameters (GET vars) for filtering and sorting

4. Response 1/2
– 1xx Informational
– 2xx Success
• 200 OK
– 4xx Client Error
• 400 Bad Request
• 403 Forbidden
• 404 Not Found
– 5xx Server Error
• 500 Internal Server Error
http://www.restapitutorial.com/httpstatuscodes.html
– XML (eXtensible Markup Language)
• Markup Validation with DTD
• Old platforms or platforms which
needs validation
• bulletProof Technology!
– JSON (JavaScript Object Notation)
• Object
• Easy to manipulate with JavaScript
• Lightweight
Data structuresHTTP code status

4. Response 2/2
XML response
JSON response
NB: data is in the body of the response

RESTFUL API
5. Authentification
14

Authentification
– No Auth
– Basic Auth
– Digest Auth
– OAuth 1.0
– Oauth 2.0
– AWS Signature
– …
We will see…
– Basic Auth
– Oauth 2.0
5. Authentification

Basic Auth
– In request headers
• "Authorization": "Basic " + api_key
• api_key = btoa(username + ":" + password);
• Base64 encoding/decoding
Security note
– Server needs SSL layer! (http(s))
– Security is managed by the server
• Firewall
• User validation
• Response
• …
5. Authentification – Basic Auth
JavaScript Example
HTTP Request

OAuth 2.0
Roles
– resource owner: generally yourself, the data owner
– resource server: server which hosts data
– client (application): an application which asks for data to the resource server
– authorization server: deliver tokens, this server can be the same as the resource
server
Tokens
– access_token
– refresh_token
Security note
– HTTPS ONLY!
5. Authentification – OAuth 2.0 – 1/9

Client registration (on authorization server)
– Application Name
– Redirect URLs
– Grant Type(s)
– Example with Symfony2 as an OAuth2 server (FOSOAuthServerBundle):
• php app/console welp:oauth-server:client:create --redirect-uri="CLIENT_HOST" --grant-
type="authorization_code" --grant-type="password" --grant-type="refresh-token" --grant-
type="token" --grant-type="client_credentials"
– Response from the server:
• Client Id
• Client Secret
– RFC 6749 — Client Registration

Grant Types
– Authorization Code Grant (authorization_code)
– Implicit Grant
– Resource Owner Password Credentials (password)
– Client Credentials (client_credentials)

Authorization Code Grant (authorization_code)

Implicit Grant (less secure)
1. The client (JS App) wants to access to your
Facebook profil
2. You are redirected to the Facebook
authorization server.
3. If you autorized access, the authorization
server redirects you to the JS web app et
expose the token access in the url
throught a callback. Callback example:
http://example.com/oauthcallback#access
_token=MzJmNDc3M2VjMmQzN.
4. You can access to the Facebook API via
JavaScript with this access token (For
example:
https://graph.facebook.com/me?access_t
oken=MzJmNDc3M2VjMmQzN).

Resource Owner Password Credentials (password)
We will
use this

Client Credentials (client_credentials)
Here, the client application needs a
tierce service without a specific user
account.
For example, our application calls to
geoip API and it is authenticated via its
client credentials in order to access to
the service.

Use the access token
– Request parameters:
https://api.example.com/resources?access_token=MzJmNDc3M2VjMmQzN
– Header Authorization:
• GET /resources HTTP/1.1
Host: api.example.com
Authorization: Bearer MzJmNDc3M2VjMmQzN

Sources
– http://oauth.net/2/
– http://tools.ietf.org/html/rfc6749
– http://tutorials.jenkov.com/oauth2/index.html
– http://www.bubblecode.net/fr/2013/03/10/comprendre-oauth2/
– https://github.com/FriendsOfSymfony/FOSOAuthServerBundle/blob/ma
ster/Resources/doc/index.md

Guidelines
– 1°: URI as resources identifier
– 2°: HTTP verbs as operator identifier
– 3°: HTTP response as resources representation
– 4°: Authentification with a token
– 5°: Security = https
6. Guidelines – 1/6

1°: URI as resources identifier
– List of resources
• NOK: https://api.example.com/resource
• OK: https://api.example.com/resources
– Filters and sorting on resources
• NOK: https://api.example.com/resources/filters/type1/sort/asc
• OK: https://api.example.com/resources?filters=type1&sort=asc
– Get a specific resource (id=5)
• NOK: https://api.example.com/resource/display/5
• OK: https://api.example.com/resources/5
– Get childs (relation) of a specific resource (id=5)
• NOK: https://api.example.com/resources/childs/5
• OK: https://api.example.com/resources/5/childs
– Get a specific child (id=46) (relation) of a specific resource (id=5)
• NOK: https://api.example.com/resources/childs/5/46
• OK: https://api.example.com/resources/5/childs/46

2°: HTTP verbs as operator identifier
– CRUD => POST: Create | GET: Read | PUT/PATCH: Update | DELETE: Delete
– Create a resource
• NOK: GET https://api.example.com/resources/create
• OK: POST https://api.example.com/resources
– Read/Get resource
• NOK: GET https://api.example.com/resources/display/98
• OK: GET https://api.example.com/resources/98
– Update resource
• NOK: POST https://api.example.com/resources/update/98
• OK: PUT https://api.example.com/resources/98
• OK: PATCH https://api.example.com/resources/98
– Delete resource
• NOK: GET https://api.example.com/resources/delete/98
• OK: DELETE https://api.example.com/resources/98

3°: HTTP response as resources representation
– HTTP response:
• HTTP code status
– 2xx
– 4xx
– 5xx
• Data structure
– JSON
– XML
– (HTML, CSV, …) less used
– Data response represents the resource

4°: Authentification with a token
– Basic Auth
• api_token = btoa(username + ":" + password);
• In request Header "Authorization": "Basic " + api_token
– OAuth2.0
• Request parameters:
https://api.example.com/resources?access_token=MzJmNDc3M2VjMmQzN
• Header Authorization:
– GET /resources HTTP/1.1
Host: api.example.com
Authorization: Bearer MzJmNDc3M2VjMmQzN

5°: Security = https
– TLS/SSL layer + tierce certificate
• Encrypt data transmission
– Avoid leaks and attacks such as:
• Man in the middle
• Stealing packet and token
• …

cURL
– http://curl.haxx.se/docs/manual.html
– CLI (Command-line Interface)
– sudo apt-get install curl php5-curl #linux debian based
– Example:
• curl -X GET -H "Authorization: Basic
dGhpcdqsdqsdqsdssdfsdfsdfsdfsdfsd==" -H "Cache-Control: no-
cache" 'http://connectedocelot.nbcorp.fr/api/devices'
7. Tools – 1/2

POSTMAN
– https://www.getpostman.com/
7. Tools – 2/2

Twitter REST APIs
– https://dev.twitter.com/rest/public
– Create a new App (https://apps.twitter.com/)
– Get Access Token
– Use the API!
8. Examples – 1/6
HTTPS
HTTPS

Twitter REST APIs
– Using POSTMAN:
– [French] Nice PHP use case:
http://www.grafikart.fr/tutoriels/php/twitter-api-tweets-100
8. Examples – 2/6

JSONPlaceholder
– http://jsonplaceholder.typicode.com/
– Fake Online REST API for Testing and Prototyping
– OpenSource:
• https://github.com/typicode/json-server
8. Examples – 3/6

PublicAPIs
• https://www.publicapis.com/
• Web APIs directory (not all APIs are RESTful)
• You can add your API
8. Examples – 4/6

Laravel REST API example
– https://github.com/Nightbr/jdn2014
– Basic Auth
– Request examples:
8. Examples – 5/6

Symfony REST API example
– http://git.nbcorp.fr/oha/oha-api
– Basic Auth
– Using:
• FosRestBundle
• NelmioApiDoc
– Full project: http://blog.nbcorp.fr/2015/02/oha-open-home-
automation/
8. Examples – 6/6

REST API with Laravel
– https://github.com/Nightbr/jdn2014/tree/master/app/api/laravel
– Routing (app/routes.php) [security Basic Auth]
9. Development – Laravel - 1/6

– Security Basic Auth (app/filters.php)

– https://laravel.com/docs/5.1/controllers#restful-resource-controllers
– REST Controller (app/controllers/CategorieController.php)

– REST Controller (app/controllers/CategorieController.php)
Exposed routes:

– Laravel tips:
– View all app route:
• php artisan route
– Create database schema:
• php artisan migrate
– Add fixtures to database
• php artisan db:seed
– A nice admin panel for Laravel:
• http://administrator.frozennode.com/
– [French] REST API tutoriel with Laravel:
• http://www.grafikart.fr/tutoriels/php/rest-503
Laravel Administrator

– Conclusion
• Lightweight RESTful API
• Very quick setup (2-4 hours max)
• Laravel framework (composer, artisan, …)
• Basic API

9. Development – Symfony- 1/13
REST API with Symfony
– Usefull bundles
• FosRestBundle: https://github.com/FriendsOfSymfony/FOSRestBundle
• NelmioApiDoc: https://github.com/nelmio/NelmioApiDocBundle
– Based on http://swagger.io/

FosRestBundle
• Setup
– Install the bundle
» composer require friendsofsymfony/rest-bundle
– Enable the bundle
» app/AppKernel.php
» new FOSRestBundleFOSRestBundle(),
– Enable a Serializer
» JMSSerializerBundle
» composer require jms/serializer-bundle
» Register it in app/AppKernel.php
» new JMSSerializerBundleJMSSerializerBundle(),

FosRestBundle
– Configuration (app/config/config.yml)
– Routing (routing.yml)
– Routing (annotation in controller)
• use FOSRestBundleControllerAnnotations as Rest;
• * @RestGet("/needs/{id}/messages", requirements={"id": "d+"}, defaults={"_format":
"json"})
– Controller extends FOSRestController

FosRestBundle
– REST Controller: method
• getClientsAction() -> GET api.domain.com/v1/clients
• getClientAction($id) -> GET api.domain.com/v1/clients/{id}
• postClientsAction(Request $request) -> POST api.domain.com/v1/clients
• patchClientsAction(Request $request, $id) -> PATCH api.domain.com/v1/clients/{id}
• deleteClientsAction($id) -> DELETE api.domain.com/v1/clients/{id}
– Tips:
• use FOSRestBundleControllerAnnotations as Rest;
• In method annotation:
– * @RestView
– * @RestView(serializerEnableMaxDepthChecks=true)

FosRestBundle
use SensioBundleFrameworkExtraBundleConfigurationSecurity;
We use FosUserBundle to manage users, here is a constraint on user
Role. It is natively managed by Symfony Security Component
http://symfony.com/doc/current/book/security.html
Enable MaxDepthChecks of the Serializer is a necessary
optimisation for huge database. For example, if my client has
Many Testbenches and TestBench has modules and also clients, I
would like to retrieve only client’s Testbenches with my client
but no more than this. So in Entity/Client.php:
See NelmioApiDoc

FosRestBundle

FosRestBundle
– Filtering & sorting
• Use ParamFetcher
– use FOSRestBundleRequestParamFetcher;
• And QueryParam annotation:
– * @RestQueryParam(name=“limit", nullable=true)
– * @QueryParam(name=“sort", nullable=true, description=“asc/desc")
• And the controller: public function getTaskAction(ParamFetcher $paramFetcher)
{
foreach ($paramFetcher->all() as $criterionName => $criterionValue) {
// some logic here, eg building query
}
$results = // query database using criteria from above
// this is just a simple example how to return data
return new JsonResponse($results);
}

FosRestBundle
– Usefull links:
• http://symfony.com/doc/current/bundles/FOSRestBundle/index.html
• http://jmsyst.com/bundles/JMSSerializerBundle
• Add extra fields using JMSSerializer:
http://stackoverflow.com/questions/15007281/add-extra-fields-using-jms-
serializer-bundle

NelmioApiDoc

NelmioApiDoc
– composer require nelmio/api-doc-bundle
– Register the bundle in app/AppKernel.php
• new NelmioApiDocBundleNelmioApiDocBundle(),
– routing.yml
– app/config/config.yml

NelmioApiDoc
– In controller:
• use NelmioApiDocBundleAnnotationApiDoc;
• And add annotation to method:
– API Documention
• http://myapp/api/doc
• php app/console api:doc:dump --format=html > api.html --no-sandbox
– https://github.com/nelmio/NelmioApiDocBundle/blob/master/Resources/doc/index.md

10. CORS – 1/3
CORS: CROSS-ORIGIN RESOURCE SHARING
– Cross-Origin Resource Sharing (CORS) is a specification that
enables truly open access across domain-boundaries. If you serve
public content, please consider using CORS to open it up for
universal JavaScript/browser access.
– http://enable-cors.org/index.html
– http://www.html5rocks.com/static/images/cors_server_flowchart
.png

10. CORS – 2/3
CORS: CROSS-ORIGIN RESOURCE SHARING
– Server Side: CORS on PHP
– Client Side:

10. CORS – 3/3
CORS: NelmioCorsBundle for Symfony2
– https://github.com/nelmio/NelmioCorsBundle
• Handles CORS preflight OPTIONS requests
• Adds CORS headers to your responses
– composer require nelmio/cors-bundle
– Register bundle
• new NelmioCorsBundleNelmioCorsBundle(),
– app/config/config.yml ->

RESTfull API
– http://blog.nicolashachet.com/niveaux/confirme/larchitecture-rest-expliquee-en-5-regles/
– https://en.wikipedia.org/wiki/Representational_state_transfer
– https://en.wikipedia.org/wiki/Web_service
– https://en.wikipedia.org/wiki/Transport_Layer_Security
– http://symfony.com/doc/current/bundles/FOSRestBundle/index.html
– http://jmsyst.com/bundles/JMSSerializerBundle
– http://stackoverflow.com/questions/15007281/add-extra-fields-using-jms-serializer-bundle
– http://www.restapitutorial.com/httpstatuscodes.html
– http://oauth.net/2/
– http://tools.ietf.org/html/rfc6749
– http://tutorials.jenkov.com/oauth2/index.html
– http://www.bubblecode.net/fr/2013/03/10/comprendre-oauth2/
– https://github.com/FriendsOfSymfony/FOSOAuthServerBundle/blob/master/Resources/doc/index.md
– http://curl.haxx.se/docs/manual.html
– https://www.getpostman.com/
– https://dev.twitter.com/rest/public
– https://apps.twitter.com/
– http://www.grafikart.fr/tutoriels/php/twitter-api-tweets-100
– http://jsonplaceholder.typicode.com/
– https://github.com/typicode/json-server
– https://github.com/Nightbr/jdn2014
– http://enable-cors.org/index.html
– https://github.com/nelmio/NelmioCorsBundle
SOURCES

Rest api titouan benoit

Recommended

Recommended

More Related Content

What's hot

What's hot (20)

Similar to Rest api titouan benoit

Similar to Rest api titouan benoit (20)

Recently uploaded

Recently uploaded (20)

Rest api titouan benoit