Convenciones en la creación de APIs REST

#Convenciones en la creación de APIs REST

Objetivos de una API:

• Sostenerse y poder crecer en el tiempo (ordenada, que respete la conceptualización del problema, que no tome atajos ni sobre categorize)
• Que lo pueda entender un tercero (alto nivel, sin detalles innecesarios de implementación, que no requiera entender todo el modelo o la historia para consumirla)

Nombres de Recursos

• Minúsculas
• Plural
• Separado por guiones medios. Como en PHP no se puede usar ese caracter se utilizan guiones bajos y luego la librería lo mapea

url :    /rest/solicitudes-alta-bienes/145
archivo: /rest/solicitudes_alta_bienes/recurso_solicitudes_alta_bienes.php

Parámetros

• Si hay "claves múltiples" (ej proyecto-versión-cambio) siempre explicitarlas:

Si: /proyectos/450/versiones/25/cambios/10
No: /cambios/450;25;10
    (no se sabe que significa el parametro 450, 25 o 10, ni si puede ir al reves 25;10;450)

• Si los parámetros son elementos del mismo tipo (ej. un listado de versiones). Se pueden separar por coma en el querystring

/proyectos/450/mejoras?versiones=10,14,25&solo_estables=0

SubAPIs

En general se prefiere utilizar el 1er nivel para describir recursos, sin contenedores que establezcan categorías. Por ejemplo

Recomendado:                 /rest/alumnos/18
No recomendado: /rest/entes/personas/alumnos/18

Si el sistema cuenta con módulos grandes que no tienen relación entre si, se pueden pensar como SubAPIs, como si fueran diferentes puntos de acceso a la API. Por ejemplo

/rest/patrimonio/bienes
/rest/viaticos/solicitudes

Aquí, la problemática de Viaticos no tiene nada que ver con los bienes patrimoniales, como si fueran 2 API's distintas metidas en el mismo sistema.

Versionado

• Vamos a utilizar el número de versión del proyecto (x.y.z) como versión de API
• Es una buena práctica no consumir este número, salvo que sea estrictamente necesario. Por ejemplo, suponiendo que uno consume Pilaga, en lugar de tratar de acomodarse a toda versión posible de API de Pilaga (y poner 200 ifs por todo el sistema) se puede indicar el número de versión minima requerida.

Lo siguiente obliga a sacar versiones de 2 digitos:

• Nuevo recurso o cambio de nombre.
• Cambio o agregado de parametros.
• Cambio en los datos que retorna el recurso.
• Resolución de bug que impacte en lo que retorna el recurso o las condiciones de error.

En cambio las siguientes modificaciones, si son permitidas en versiones menores (de 3 dígitos):

• Refactoring interno (que no cambia lo anterior)
• Cambios documentación
• Cambios en mensajes de error

Testing

Las APIs son una interface mas del sistema, aunque no son visuales, por lo tanto, no es posible probar uno a uno los recursos como si fueran operaciones y botones. Es necesario probar por código, para eso se utiliza PHPUnit, ver Testing de APIs REST.

Documentación

La consola swagger debería utilizarse para documentación de recursos y parámetros.