Índice
Convenciones sobre el manejo de las URI
A continuación se describen las convenciones sobre las cuales se desarrolló el API de Evolution Connect.
API Concreta
El API está pensado para que sea concreto, en oposición a un API abstracto, evitando crear recursos genéricos, tales como “entidad”, en su lugar se utilizará “amonestación”, “solicitudLicencia”, “HoraExtra”, etc. Ya que un API concreto es más descriptivo y comprensible para el programador.
Formato de las URI, utilizando sujetos y no verbos.
Un api tiene “endpoints” que son puntos de acceso a los recursos. La buena práctica dicta que un API debe usar nombres para los endpoints y no verbos. Para ilustrar esta situación se presenta un ejemplo:
| Ejemplos de Endpoints que usan Verbos | Ejemplos de Endpoints que usan Sujetos (Nombres) |
|---|---|
| /getAllBlogPost /getAllRecentBlogPost |
GET /blogposts GET /blogposts/?recent=true |
| /addBlogPost/12 | POST /blogposts (en el Body se envían datos) |
| /updateBlogPost/12 | PUT /blogposts (en el Body se envían datos) |
| /deleteBlogPost/12 | DELETE /blogposts/12 |
| /getAuthorById/3 | GET /authors/3 |
| /updateAuthor/3 | PUT /authors (en el Body se envían datos) |
| /deleteAuthor/3 | DELETE /authors/3 |
| /getAuthorBlogPost/3 | GET /authors/3/blogposts |
La diferencia más apreciable, es que existen muchos más endpoints cuando utilizamos verbos en lugar de sujetos, en el ejemplo, cuando se usan verbos cada renglón es un endpoint diferente.
Mientras que, al utilizar sujetos, toda la columna de la derecha tiene solamente 2 endpoints “blogposts” y “authors” y las operaciones se especifican por el verbo HTTP que se utiliza, y por los parámetros enviados en el “querystring” de la URL o en el “Body” de la petición.
Es evidente que la documentación quedará más simple y consistente y los desarrolladores entenderán más rápidamente cómo se debe utilizar el API.
Finalmente, es importante señalar que el nombre del sujeto se utilizará en singular y no en plural. Para evitar ambigüedades relacionadas con las palabras compuestas, por ejemplo, un endpoint llamado TipoIncapacidad, se tomará como estándar que la primera palabra se refiere a la entidad que se está exponiendo al API.
Utilizar sub-recursos para obtener información de las relaciones de las entidades.
Si un recurso está relacionado con otro, y esta relación es de dependencia directa, como sería el caso de una Incapacidad y la lista de períodos procesados; o un Evento de Capacitación y la lista de instructores o de la programación de horas del evento, entonces se para acceder a esta información relacionada, se debe especificar un sub-recurso en la URI.
Algunos ejemplos:
GET /incapacidades/234/periodos
GET /puestos/100/competencias
GET /puestos/100/competencias/35/subcompetencias
Como puede verse en los ejemplos, esto no está limitado a un solo nivel, sino que a necesidad del recurso puede ampliarse a niveles más profundos en la jerarquía de relaciones.
El último ejemplo se debe leer como: obtenga la lista de subcompetencias perteneciente a la competencia 35 que está asociada al puesto 100. Este mecanismo permite obtener únicamente los registros de las tablas detalle, una vez ya se obtuvo la información del recurso principal.