Desarrollo de APIs REST

Arquitecturas REST

Las arquitecturas REST comparten las siguientes características.

• Sin estado(Stateless): Las arquitecturas REST no mantienen estado lo que les permite ser más escalables.
• Orientada a Recursos: Siendo un recurso un elemento de información accesible con un identificador global único
• Operaciones Definidas: Un conjunto de operaciones estándar definidas que se aplican a cada uno de los recursos (GET,POST,PUT,DELETE etc).
• HiperMedia: Definición de enlaces o vínculos que nos permiten navegar entre los diferentes recursos.

Niveles de madurez REST

Las arquitecturas REST se dividen en cuatro niveles de madurez (Modelo Richardson):

• Nivel 0: En el nivel 0 se usa HTTP como mecanismo de transporte a la hora de acceder de forma remota al servidor y obtener sus datos . Habitualmente se utilizan peticiones POST y XML/JSON para comunicarnos con el servidor (Plain Old XML) conectándonos a una URL concreta.
• Nivel 1: Es el primer paso hacia un mejor enfoque. En el se define el concepto de Recurso . A partir de este momento en vez de realizar peticiones HTTP a un único endpoint comenzamos a realizar peticiones a recursos individuales cada uno de ellos dispone de una URL única de acceso como por ejemplo /personas.
• Nivel 2: En este nivel hay un cambio importante comparado con los anteriores. En los anteriores la mayoría de la gente realiza todas las peticiones usando GET o POST. A partir de este nivel pasamos a realizar las peticiones utilizando HTTP Verbs, concretamente de la siguiente forma:
  • GET: Obtención de información de un Recurso
  • POST: Inserción de nueva información del Recurso
  • PUT: Actualización de la información del Recurso
  • DELETE: Borrado de la información de un Recurso
• Nivel 3 : Este es el nivel más exigente y permite que cuando nosotros devolvamos información sobre un Recurso vía GET este puede contener enlaces a otros Recursos relacionados (HATEHOAS).

Otras normas

• Los recursos estarán en formato camel case y siempre en plural.
• Los servicios deberán aceptar tanto peticiones en formato XML como en formato JSON. La respuesta igualmente será JSON o XML en función de la petición.

Contexto y versionado

Cada vez que se modifique un método de la API se correrá la versión de la misma. El path base será siempre "webapi" seguido de la versión.

http://<host>:<puerto>/<app>/webapi/<version>

Documentación y pruebas

Toda funcionalidad expuesta en una aplicación en forma de API Rest deberá estar documentada y probada.

Documentación

Por cada servicio se deberá documentar los siguientes puntos:

• URL
  • Método HTTP
  • Parámetros de entrada: nombre, tipo (formato), obligatoriedad
  • Parámetros de salida

Se recomienda el uso de la herramienta Swagger.

Pruebas

Junto a la documentación, se deberá entregar un proyecto Postman en formato "JSON Collection v.2.1" con scripts de test para cada petición.

Estos scritps pasarán a formar parte del proceso de CI y en caso de no cumplirse las aserciones, el proyecto no será desplegado en los servidores de Gobierno.

Checklist de calidad

Puede descargar el checklist de calidad desde la sección de QA.