Representational State Transfer (aka REST) (http://en.wikipedia.org/wiki/Representational_state_transfer) és un estil que s'aplica en l'arquitectura de programari que consisteix en una sèrie de guies i bones pràctiques per a la creació de serveis web (web services) escalables.
REST està guanyant importància respecte a altres alternatives a l'hora de crear serveis web com per exemple SOAP o serveis web basats en WSDL. Els sistemes RESTful tipicament però no sempre utilitzant el protocol Hypertext Transfer Protocol i els HTTP verbs del protocol (GET, POST, PUT, DELETE, etc.) per tal de comunicar-se amb el servei web i obtenir l'accés a recursos.
L'arquitectura REST és desenvolupada per W3C Technical Architecture Group (TAG) en paral·lel al desenvolupament de HTTP 1.1. El concepte WWW o World Wide Web representa la major implementació d'un sistema amb una arquitectura tipus REST però sovint és més utilitzant en programació de serveis web per exemple per implementar CRUD
NOTA: tenen ja els seus anys i són força obsoletes (actualment parlariem només de REST, de JSON en comptes XML però són encara útils com a referència històrica)
Les APIs de serveis web (Web service) que s'adhereixen a les restriccions de l'arquitectura REST són anomenades RESTful APIs.
Les RESTful APIs basades en HTTP tenen en compte els següents aspectes:
Altres:
A RESTful API is an HTTP server for getting a list of resources, creating, updating, and deleting (CRUD) one single resource, based on a minimal specification. In fact the specification is the HTTP standard itself (see the HTTP RFC 2616 specifications). Actions are defined with HTTP method verbs: GET, POST, PUT, DELETE, and PATCH. Responses are meant to be interpreted by a machine. They are generaly describe as JSON, following the JSON Schema specifications.
Resources:
Una API RESTful (RESTful API)) ha d'utilitzar el mètodes HTTP per implementar CRUD:
NOTA: Recordeu CRUD és Create Retrieve Update Delete
Vegeu també HTTP
HTTP status codes in the response body tells client application what action should be taken with the response. For an example if the response code 200, it means on the server side the request is processed successfully and you can expect updated data in the response. As well if the status code is 401, the request is not authorized. An example cause for 401 could be api key is invalid.
It is not necessary to support all HTTP status codes, but supporting at least the following codes should be good enough. Check out list of http codes from restapitutorial.com and Wikipedia
200 OK 201 Created 304 Not Modified 400 Bad Request 401 Unauthorized 403 Forbidden 404 Not Found 422 Unprocessable Entity 500 Internal Server Error
In REST design the URL endpoints should be well formed and should be easily understandable. Every URL for a resource should be uniquely identified. If your API needs an API key to access, the api key should be kept in HTTP headers instead of including it in URL.
For an example:
GET http://abc.com/v1/tasks/11 – Will give the details of a task whose id is 11
POST http://abc.com/v1/tasks – Will create a new task
There is a huge discussion on API versioning whether to maintain api version in the URL or in the HTTP request headers. Even though it is recommended that version should be included in the request headers, I feel comfortable to maintain it in the URL itself as it is very convenient on the client side to migrate from one version to another.
Example:
http://abc.com/v1/tasks
http://abc.com/v2/tasks
Els tipus de dades més utilitzats en APIs web són XML i JSON.
Per a JSON el Mime type ha de ser:
Content-Type: application/json,
per a XML:
Content-Type: application/xml.
Consulteu MIME (MIME Types).
Recursos:
Vegeu API Key
Recursos:
NOTA: Consulteu Desenvolupaments_APIS_web#Autenticaci.C3.B3
Tenim múltiples opcions:
Enllaços externs:
Consulteu Desenvolupaments_APIS_web#REST_web_API
TODO
http://docs.aws.amazon.com/AmazonS3/latest/dev/RESTAuthentication.html
Vegeu Laravel i Laravel REST
Vegeu Flask
Vegeu json-server
What is RAML API description ?
How would you specify a REST API? The best answer is to look for standards. RESTful API Modeling Language (RAML) is a simple and succinct way of describing practically-RESTful APIs using YAML. It "encourages reuse, enables discovery and pattern-sharing, and aims for merit-based emergence of best practices".
A RAML file describes the request and response format of a REST API. It looks like this:
Acacha Wiki#%RAML 0.8
title: World Music API
baseUri: http://example.api.com/{version}
version: v1
traits:
- paged:
queryParameters:
pages:
description: The number of pages to return
type: number
- secured: !include http://raml-example.com/secured.yml
/songs:
is: [ paged, secured ]
get:
queryParameters:
genre:
description: filter the songs by genre
post:
/{songId}:
get:
responses:
200:
body:
application/json:
schema: |
{ "$schema": "http://json-schema.org/schema",
"type": "object",
"description": "A canonical song",
"properties": {
"title": { "type": "string" },
"artist": { "type": "string" }
},
"required": [ "title", "artist" ]
}
application/xml:
delete:
description: |
This method will *delete* an **individual song**
Vegeu Desenvolupaments_APIS_web i codeigniter-restserver i
https://github.com/chriskacerguis/codeigniter-restserver
https://laracasts.com/series/whip-monstrous-code-into-shape/episodes/16
vegeu Laravel REST
Vegeu angularJS, Angular i REST i Restangular
Vegeu Swagger