Buenas Practicas API

Construcción de URL

  • Se recomienda usar la siguiente estrucura de url: {base_url}/api/{service_name}/v{version}/{resource} ejemplo : https://api.coderhouse.com/api/platform/v2/student
  • Preferimos y recomendamos la nomenclatura de los recursos y rutas en ingles.
    • Se adaptará mejor a una posible generación de la marca blanca en un futuro.
  • Las funciones de create, read, update, delete no deben ser usadas en la URL , en lugar de eso se deben usar los verbos/metodos HTTP (POST, GET, PUT, PATCH, DELETE)
  • No incluir ni aceptar la barra invertida / al final de la ruta ó endpoint
  • La barra invertida / solo debe usarse para indicar una separación en la jerarquia de las relaciones
  • Usar guion medio - en lugar de guion bajo _
  • Preferentemente usar todo lowercase
  • Palabras en plural deberan usarse para referirse a colecciones de recursos y recurso principal api/platform/v2/desafios
  • En singular solo si se apunta a un solo recurso o recursos unicos api/platform/v2/session

Parametros en url

  • El parametro lean indica cuando se requiera un recurso "ligero" o sin los recursos relacionados incluidos (solo referencias)
  • El parametro ts se enviará eventualmente con el timestamp en ms para evitar el cacheo de los datos
  • Se recomienda la inclusión del parametro fields en la ruta para poder (en caso de ser requerido) indicar que campos se desean obtener del recurso
    • GET /courses?fields=id,name,camadas,updated_at

Otras cosideraciones

  • Una llamada Update o Create (PUT, POST, PATCH) deberia devolver el recurso completo asi se evitara tener que hacer otra llamada del recurso actualizado