Buenas Prácticas sobre APIs Web I

Keep base URL simple and intuitive

· La URL base es la parte fundamental de nuestra API Web.

· Una URL base simple e intuitiva permite que nuestra API sea sencilla.

Sólo 2 URLS bases por objeto

• La primera URL se usa para una colección

• La segunda URL para un elemento específico de una colección

No usar verbos en URL bases

· Algunas APIS Web usan una aproximación method-driven para el diseño de las URLs, estas suelen contener verbos, a veces al principio a veces al final lo que siempre lleva a una larga lista de URLS no consistentes:

Usar Operaciones HTTP para operar sobre las colecciones y elementos

• Las operaciones HTTP son POST, GET, PUT y DELETE que usaremos para el CRUD:

POST – CRUD (Create)

GET — CRUD (Read)

PUT — CRUD (Update)

DELETE – CRUD (Delete)

Uso de plurales

• Es importante ser consistente sobre todo. Siempre usar singular o siempre plural.

• En nuestra aproximación proponemos usar el plural del objeto a tratar:

Nombres concretos

• Se debe evitar URLS del tipo /ítems o /assets

• Y en su lugar usar /blogs, /videos, /news,…

TRATAMIENTO DE ERRORES

• Existen diversas aproximaciones:

· Facebook por ejemplo siempre devuelve un 200 (OK),

· Twilio alinea los errores con los códigos de estado HTTP y además devuelve un código de error propio.

· SimpleGeo también devuelve código estándar pero sin valor adicional.

Opción 1: Usar códigos de estado HTTP

· Usar códigos de estado HTTP e intentar mapearlos con códigos relevantes de la aplicación.

· Existen 70 códigos HTTP que nadie conoce completamente, por lo que se usará un subconjunto de estos.

· Códigos de estado HTTP a usar: Existen 3 códigos básicos:

· Todo OK

· Error de aplicación à error cliente

· Error del API à error servidor

Que mapearemos así:

· Todo OK à 200 (OK)

· Error de aplicación à 400 (Bad Request)

· Error del API à 500 (Internal Server Error)

· Devolver mensajes detallados en el payload

VERSIONADO

· Existen muchas formas:

· Nombrado:

· Especificar la versión con prefijo v

· Usar un número ordinal simple (1,2,10,100)

· No usar notación v1.2, ya que representa granularidad de versión

· Versión no debe ir en Header HTTP

· Nunca publicar un Servicio sin versión.

· Nuestro ejemplo /dogs se convertiría en /v1/dogs

PAGINACIÓN

· Es una mala idea devolver todo lo que está en BD.

· Para la paginación Facebook usa offset y limit, Twitter usa page and rpp (records per page), LinkedIn usa start y count.

• Usar limit y offset que es entendido en BD.
• Para recuperar elementos del 50 al 75 haría:

/dogs?limit=25&offset=50

• Incluir metadata en cada respuesta con el número total de registros disponibles.
• Paginación por defecto: si no se pone nada =

limit=10&offset=0