IMPORTANT: Per accedir als fitxer de subversion: http://acacha.org/svn (sense password). Poc a poc s'aniran migrant els enllaços. Encara però funciona el subversion de la farga però no se sap fins quan... (usuari: prova i la paraula de pas 123456)

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

Documentació/Transparències

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)


Conceptes

RESTful

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:

Què és una API RESTful?

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:

Característiques d'una API RESTFul

Ús del protocol HTTP

Una API RESTful (RESTful API)) ha d'utilitzar el mètodes HTTP per implementar CRUD:

  • GET: per obtenir (R->Retrive) un recurs. Per obtenir múltiples recursos es sol indicar dos tipus de recurs el single i el plural: user i users per exemple
  • PUT: Per a crear un recurs (C->Create)
  • POST/PATCH: Per actualitzar un recurs (U->Update)
  • DELETE: Per esborrar un recurs (D->Delete)

NOTA: Recordeu CRUD és Create Retrieve Update Delete

Vegeu també HTTP

HTTP Status Code

HTTP Status Code

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

URL Structure

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

API Versioning

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

Content Type

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:

Autorització i Autenticació

API Key

Vegeu API Key

Recursos:

Autenticació

NOTA: Consulteu Desenvolupaments_APIS_web#Autenticaci.C3.B3

Tenim múltiples opcions:

Enllaços externs:

Altres alternatives

Desenvolupament

Consulteu Desenvolupaments_APIS_web#REST_web_API

APIS públiques

Amazon

TODO

http://docs.aws.amazon.com/AmazonS3/latest/dev/RESTAuthentication.html

REST servers

PHP

Laravel

Vegeu Laravel i Laravel REST

Phyton

Flask

Vegeu Flask


Javascript

json-server

Vegeu json-server

REST clients

Extensions de navegadors

Firefox

Chrome

RAML

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:

#%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**

Desenvolupaments_APIS_web

Vegeu Desenvolupaments_APIS_web i codeigniter-restserver i

https://github.com/chriskacerguis/codeigniter-restserver

Format de les URLs

https://laracasts.com/series/whip-monstrous-code-into-shape/episodes/16

PHP

CodeIgniter

Laravel

vegeu Laravel REST

Javascript

Angular

Vegeu angularJS, Angular i REST i Restangular

Documentació web d'APIS

SwaggerUI

Vegeu Swagger

Vegeu també

Enllaços externs