Política de desarrollo de servicios API-REST

Requerimientos generales

  • Debe ser diseñado y orientado para ser implementado por un desarrollador.
  • La documentación del API-REST debe ser actualizada constantemente.
  • Debe ser sencilla e intuitiva.

Nombres y métodos

Los nombres que forman parte de la ruta deben estar en español-castellano y en plural.
Se recomienda utilizar sustantivos en lugar de verbos.
Por ejemplo:

Método Ruta Descripción
GET /usuarios Obtiene el listado de todos los usuarios.
GET /usuarios/12 Obtiene un usuario específico.
POST /usuarios Crea un nuevo usuario.
PUT /usuarios/12 Actualiza el usuario #12
PATCH /usuarios/12 Actualiza parcialmente el usuario #12.
DELETE /usuairos/12 Elimina el usuario #12.
Acerca de las relaciones entre datos, se debe concatenar las rutas siguiendo la nomenclatura antes mencionada.
Método Ruta Descripción
GET /usuarios/12/comentarios Obtiene el listado de todos los comentarios del usuario 12.
GET /usuarios/12/comentarios/6 Obtiene el comentario #5 del usuario #12.
POST /usuarios/12/comentarios Crea un nuevo comentario para el usuario #12.
PUT /usuarios/12/comentarios/6 Actualiza el comentario #6 para el usuario #12.
PATCH /usuarios/12/comentarios/6 Actualiza parcialmente el comentario #6 para el usuario #12.
DELETE /usuarios/12/comentarios/5 Elimina el comentario #5 para el usuario #12.
En los métodos que envían datos al servicio (POST, PUT, PATCH), el cuerpo de la información debe estar en formato JSON.

OPTIONS

Permite al cliente determinar los métodos que admite el servicio y los requerimientos asociados al recurso.
Mínimamente la respuesta de este método debe contener el estado 200 OK y la cabecera con la etiqueta Allow con el listado de los métodos admitidos por el recurso.
200 OK
Allow: GET,POST,PUT,PATCH,DELETE,OPTIONS

Paginación

  • La cantidad de items por defecto es de 30, para especificar la cantidad de items por página se utiliza el parámetro limite.
?limite=100
  • Para recorrer los registros desde un determinado punto se utiliza el parámetro intervalo.
?intervalo=45
Para navegar entre los resultados de la solicitud se combina los siguientes parámetros: limite e intervalo.
Por ejemplo para paginar resultados de 25 items por página, se pueden utilizar las siguientes rutas:
Ruta Nº página
/usuarios?limite=25 1
/usuarios?limite=25&intervalo=25 2
/usuarios?limite=25&intervalo=50 3
/usuarios?limite=25&intervalo=75 4
La navegación debe realizarse a través de enlaces: siguiente, anterior, primera página y última página los cuales deben estar indicadas en la cabecera 'link'.
Link: <https://www.midominio.com/datos/api/v1/usuarios?limite=25&intervalo=75>; rel="siguiente",
<https://www.midominio.com/datos/api/v1/usuarios?limite=25&intervalo=200>; rel="último",
<https://www.midominio.com/datos/api/v1/usuarios?limite=25&intervalo=0>; rel="primero",
<https://www.midominio.com/datos/api/v1/usuarios?limite=25&intervalo=25>; rel="anterior",
  • Especificar el orden de los campos con el parámetro orden seguido del nombre del campo, el orden por defecto es Ascendente, cuando se desea especificar el orden Descendente se específica con el carácter -.
?orden=nombre
Cuando se necesite ordenar los resultados por mas de 1 campo se utiliza el caracteres separador ',' (coma) entre los parámetros.
?orden=nombre,-documento
  • Para especificar los campos que debe retornar la solicitud se debe especificar el parámetro campos, seguido de los campos separados por ',' (coma), Se recomienda que el API no retorne el total de los campos del recurso, es decir solamente retornar los campos esenciales.
?campos=nombre,apellido,ci,lugar

SSL

Siempre usar SSL, la ventaja de usar SSL es que las comunicaciones cifradas simplifican los esfuerzos de autenticación.

Búsquedas

Las consultas por palabra se deben realizar mediante el parámetro q seguido del texto buscado.
?q=juan%20perez

Formato de respuestas

Las respuestas por defecto deben estar en formato JSON, para especificar otro formato se realiza mediante parámetro formato.
?formato=xml

Utilizar estados HTTP

Toda solicitud debe tener una respuesta, aún cuando esta represente un error. Los códigos de error disponibles son:
  • 200 – OK – Estado por defecto.
  • 201 – OK – Nuevo recurso creado.
  • 204 – OK – Recurso eliminado correctamente.
  • 304 – Not Modified – El cliente puede usar cache de datos.
  • 400 – Bad Request – La solicitud es inválida o no puede ser atendida. La descripción del error puede estar descrita en el payload de la respuesta.
  • 401 – Unauthorized – La solicitud requiere autenticación de usuario.
  • 403 – Forbidden – El servidor ha comprendido la solicitud, pero el acceso no es permitido.
  • 404 – Not found – No existe el recurso para la URI.
  • 422 – Unprocessable Entity – Debería utilizarse si el servidor no puede procesar la entidad, por ejemplo si una imagen no puede ser formateada o datos requeridos no fueron enviados en la petición.
  • 500 – Internal Server Error – Error interno del servidor.

Seguridad

Todos los datos que admite el servicio deben ser sanitizados para evitar ataques de inyección.
Se recomienda utilizar JWT (JSON Web Token) para cifrar la transmisión de información cuando se requiera autenticar y realizar intercambio de información.

Errores

Cuando se produce un error en el acceso a un recurso se debe retornar los datos del error según la siguiente estructura:

  1. Código del error general.
  2. Mensaje del error general.
  3. Listado de errores específicos.
  4. Código del primer error específico.
  5. Nombre del primer campo involucrado en el error.
  6. Mensaje del primer error específico.

Comentarios