Rest api titouan benoit

RESTful API Titouan BENOIT – CTO at Welp.fr [email protected]

RESTful API – Titouan BENOIT

Titouan BENOIT – CTO at Welp – [email protected]

– [email protected]

RESTful API - v1.0 2

Titouan BENOIT

mailto:[email protected]

mailto:[email protected]

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

RESTFUL API

1. Introduction

4


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


RESTFUL API

2. RESTful API

6


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

http://myapi.domain.com/resources/2

http://myapi.domain.com/foos/3

http://myapi.domain.com/resources/2

http://myapi.domain.com/foos/3

http://myapi.domain.com/resources

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

RESTFUL API

4. Response

11

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 structures HTTP 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



http://tools.ietf.org/html/rfc6749





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_token=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



http://oauth.net/2/

http://oauth.net/2/



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



RESTFUL API

6. Guidelines

26


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

• …



RESTFUL API

7. Tools

33


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

http://curl.haxx.se/docs/manual.html



POSTMAN

– https://www.getpostman.com/


7. Tools – 2/2

https://www.getpostman.com/


RESTFUL API

8. Examples

36


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

https://dev.twitter.com/rest/public


https://apps.twitter.com/



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

http://jsonplaceholder.typicode.com/


https://github.com/typicode/json-server





PublicAPIs • https://www.publicapis.com/

• Web APIs directory (not all APIs are RESTful)

• You can add your API


8. Examples – 4/6

https://www.publicapis.com/

https://www.publicapis.com/


Laravel REST API example

– https://github.com/Nightbr/jdn2014

– Basic Auth

– Request examples:


8. Examples – 5/6

https://github.com/Nightbr/jdn2014



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

http://git.nbcorp.fr/oha/oha-api




http://blog.nbcorp.fr/2015/02/oha-open-home-automation/








RESTFUL API

9. Development

43


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

https://github.com/Nightbr/jdn2014/tree/master/app/api/laravel

https://github.com/Nightbr/jdn2014/tree/master/app/api/laravel



– Security Basic Auth (app/filters.php)




REST API with Laravel – https://laravel.com/docs/5.1/controllers#restful-resource-controllers

– REST Controller (app/controllers/CategorieController.php)



https://laravel.com/docs/5.1/controllers








– REST Controller (app/controllers/CategorieController.php)



Exposed routes:




REST API with Laravel – 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

http://administrator.frozennode.com/

http://administrator.frozennode.com/

http://www.grafikart.fr/tutoriels/php/rest-503








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

https://github.com/FriendsOfSymfony/FOSRestBundle

https://github.com/FriendsOfSymfony/FOSRestBundle

https://github.com/nelmio/NelmioApiDocBundle

https://github.com/nelmio/NelmioApiDocBundle

http://swagger.io/

http://swagger.io/




FosRestBundle • Setup

– Install the bundle

» composer require friendsofsymfony/rest-bundle

– Enable the bundle

» app/AppKernel.php

» new FOS\RestBundle\FOSRestBundle(),

– Enable a Serializer

» JMSSerializerBundle

» composer require jms/serializer-bundle

» Register it in app/AppKernel.php

» new JMS\SerializerBundle\JMSSerializerBundle(),




FosRestBundle

– Configuration (app/config/config.yml)

– Routing (routing.yml)

– Routing (annotation in controller) • use FOS\RestBundle\Controller\Annotations as Rest;

• * @Rest\Get("/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 FOS\RestBundle\Controller\Annotations as Rest;

• In method annotation:

– * @Rest\View

– * @Rest\View(serializerEnableMaxDepthChecks=true)




FosRestBundle use Sensio\Bundle\FrameworkExtraBundle\Configuration\Security; 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

http://symfony.com/doc/current/book/security.html

http://symfony.com/doc/current/book/security.html




FosRestBundle




FosRestBundle – Filtering & sorting

• Use ParamFetcher

– use FOS\RestBundle\Request\ParamFetcher;

• And QueryParam annotation:

– * @Rest\QueryParam(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

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

















NelmioApiDoc




NelmioApiDoc – composer require nelmio/api-doc-bundle

– Register the bundle in app/AppKernel.php

• new Nelmio\ApiDocBundle\NelmioApiDocBundle(),

– routing.yml

– app/config/config.yml




NelmioApiDoc

– In controller:

• use Nelmio\ApiDocBundle\Annotation\ApiDoc;

• 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

https://github.com/nelmio/NelmioApiDocBundle/blob/master/Resources/doc/index.md

https://github.com/nelmio/NelmioApiDocBundle/blob/master/Resources/doc/index.md

RESTFUL API

10. CORS

63



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

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 Nelmio\CorsBundle\NelmioCorsBundle(),

– app/config/config.yml ->

https://github.com/nelmio/NelmioCorsBundle



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

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

https://en.wikipedia.org/wiki/Web_service

https://en.wikipedia.org/wiki/Web_service

https://en.wikipedia.org/wiki/Transport_Layer_Security






















http://oauth.net/2/

http://oauth.net/2/






































Rest api titouan benoit

Software

Transcript of Rest api titouan benoit