La representación de data en REST se llama Resource, y se usa para tener una naming convention consistente. Esto tendrá el beneficio de que sea mucho más fácil trabajar con la API y el proyecto estará más ordenado que siempre es un beneficio al momento de hacer debuging o manutención.

---

Convenciones varias

• Usar / para definir jerarquía
• No terminar las URL con /
• Separar palabras con guiones '-'. Por ejemplo, 'user-admin' en vez de 'UserAdmin'
• No usar guion bajo '_' . Algunos navegadores los esconden y puede generar errores a veces.
• Usar minúsculas siempre para mantener consistencia
• No usar la extensión de los archivos como .xml

---

Que es un Resource

Cualquier información que puede ser nombrada (un servicio, un documento, una imagen, una persona)

En general, hay que usar sustantivos, excepto en casos especificos como los controladores

The key abstraction of information in REST is a resource. Any information that can be named can be a resource: a document or image, a temporal service (e.g. “today’s weather in Los Angeles”), a collection of other resources, a non-virtual object (e.g., a person), and so on. In other words, any concept that might be the target of an author’s hypertext reference must fit within the definition of a resource. A resource is a conceptual mapping to a set of entities, not the entity that corresponds to the mapping at any particular point in time.

---

Arquetipos de Resource

Los Resources se pueden clasificar en distintos arquetipos para clasificarlos y, además, no hacer que un resource haga demasiado.

Si un resource clasifica como más de uno a la vez, probablemente se debería separar en dos separados.

Collection

• Es un directorio de recursos, por ejemplo, una lista de objetos o filas en una tabla. Usar prural

domain/resource/collection

domain.com/user-admin/users

Document

• Un objeto único, similar a una instancia de un objeto o una fila en una tabla. Se pueden visualizar como un objeto dentro de una colección o no. Usar singular

domain/resource/collection/document

domain.com/user-admin/users

Store

• Es un repositorio de recursos que maneja el cliente. Es para cosas que el cliente le hace CRUD a los registros. Usar plural

domain/resource/collection/document/store

domain.com/user-admin/users/{user_id}/services

Controller

• Es una acción, como un método con argumentos y salidas. No usar tanto, se prefiere el uso de HTTP Request Methods, pero para otras funcionalidades se puede usar este arquetipo Usar verbos

domain/resource/collection/controller

domain.com/user-admin/users/{user_id}/delete

---

No Utilizar acciones CRUD en URIs

No utilizar palabras como create o update en nombres de URI, estas solo deben identificar resources, no las acciones que se les hace.

Para hacer eso se usan HTTP request methos como GET, POST, PUT or DELETE

Por ejemplo

• HTTP GET initial-d.jaramillo.cl/users/{id} // Consigue la info de un usuario (READ)

• HTTP PUT initial-d.jaramillo.cl/users/{id} // Actualiza la info de un usuario (UPDATE)

• HTTP DELETE initial-d.jaramillo.cl/users/{id} // Elimina a un usuario (DELETE)

• HTTP POST initial-d.jaramillo.cl/users // Agrega un nuevo usuario (INSERT)

Los datos para hacer las acciones se guardan en el HEADER de la request, usualmente en un formulario o un json

Cuando Usar Composición

Solo usar composición para ordenar, paginar, filtrar o acciones similares

La composición se le llama a cuando se usan ? para poner argumentos, por ejemplo

• initial-d.jaramillo.cl/users?user-type=Cajero