REST, REpresentational State Transfer, es un tipo de arquitectura de desarrollo web que se apoya totalmente en el estándar HTTP.
REST nos permite crear servicios y aplicaciones que pueden ser usadas por cualquier dispositivo o cliente que entienda HTTP, por lo que es increíblemente más simple y convencional que otras alternativas que se han usado en los últimos diez años como SOAP y XML-RPC.
REST se definió en el 2000 por Roy Fielding, coautor principal también de la especificación HTTP. Podríamos considerar REST como un framework para construir aplicaciones web respetando HTTP.
Por lo tanto REST es el tipo de arquitectura más natural y estándar para crear APIs para servicios orientados a Internet.
Nunca se guarda el estado en el servidor, asi todos los datos que se requieren para mostrar la información que se solicita debe estar en la consulta por parte del cliente.
Al no guardar estado, REST nos da mucho juego, ya que podemos escalar mejor sin tener que preocuparnos de temas como el almacenamiento de variables de sesión e incluso, podemos jugar con distintas tecnologías para servir determinadas partes o recursos de una misma API.
Aparte de los requisitos básicos que se indican en la página principal del Área de Desarrolladores, debemos disponer de una aplicación registrada en OcioAvila.com. Al crear una nueva aplicación se facilitan dos datos: el ConsumerKey y el ConsumerToken.
La clave ConsumerKey identifica la aplicación que utilizará la API. Traduciendo literalmente podríamos decir que es la llave que identifica a la aplicación, mientras que el ConsumerToken es la contraseña de acceso. Ambas claves se generan automáticamente y deben mantenerse en secreto. Si las claves se ven comprometidas pueden generarse unas nuevas, quedando invalidadas las antiguas.
Usando el ConsumerKey y el ConsumerToken en el servicio auth/app se devuelve una nueva clave se devuelve una contraseña de paso o AccessToken. La cadena AccessToken debe incluirse siempre en la llamada al resto de métodos de la API, mediante la url, añadiendo al final el parámetro "access_token=" y el valor obtenido.
Cada AccessToken está asociada a un usuario y supone el inicio de sesión en OcioAvila.com de forma idéntica a lo que ocurre cuando se escribe el nombre de usuario y la contraseña habitual. Cuando una aplicación solicita un AccessToken, se genera una clave válida para el propietario de la misma. Si se desea obtener una válida para otro usuario registrado hay que usar el servicio OAuth.
Los AccessToken tienen una vida muy limitada, no superior a dos horas, que se extiende de forma automática cada vez que se usa. Si la aplicación que las va a usar requieren una validez mayor se puede extender la vida de las mismas durante 60 días. Extender la vida es muy útil para aplicaciones móviles que no van a hacer uso de los métodos de usuario pues los datos que facilitará la API serán los del propietario de la aplicación y no los del usuario de la app.
Actualmente la API de OcioAvila.com sólo dispone de métodos GET o de obtención de recursos. Esto significa que podemos obtener datos de la web pero no enviarlos.
La mayoría de los recursos se entregan en formato JSON, salvo en los casos que se indican. Si se produce un error de autenticación, se devuelve el mensaje de error también en el mismo formato con la descripción del mismo
Los textos entre los simbolos < y > marcados en color azul son variables y deben ser sustituidos por el valor requerido en cada consulta
Los textos entre corchetes [ y ] son parámetros opcionales. Algunos parámetros opcionales requieren del uso en conjunto con otros. Obsérvese que cuando esto sea así se mostrarán ambos encerrados por un grupo de corchetes.
El caracter de barra / es el separador entre parámetros y debe usarse siempre delante de los parámetros opcionales. Por eso siempre detrás de la apertura del corchete [ hay una barra.