Capítulo 3: Operaciones CRUD en OData
Uno de los pilares fundamentales de OData, heredado de los principios REST, es la capacidad de realizar operaciones básicas de manipulación de datos sobre los recursos expuestos por el servicio. Estas operaciones se conocen comúnmente por el acrónimo CRUD: Create (Crear), Read (Leer), Update (Actualizar) y Delete (Eliminar). OData estandariza cómo estas operaciones se mapean a los métodos HTTP estándar.
Introducción a las Operaciones CRUD
Las operaciones CRUD permiten a los clientes interactuar con los datos gestionados por el servicio OData de una manera uniforme y predecible. Cada operación CRUD se corresponde directamente con un método HTTP específico, aplicado a la URI del recurso que se desea manipular 6:
Create (Crear): Se utiliza para añadir nuevos recursos (entidades) a una colección. Se mapea al método HTTP POST.
Read (Leer): Se utiliza para recuperar recursos, ya sea una colección de entidades, una entidad individual o propiedades específicas. Se mapea al método HTTP GET.
Update (Actualizar): Se utiliza para modificar recursos existentes. Puede ser una actualización completa (reemplazo) o parcial. Se mapea a los métodos HTTP PUT, PATCH o MERGE.
Delete (Eliminar): Se utiliza para eliminar un recurso existente. Se mapea al método HTTP DELETE.
Este capítulo detallará cada una de estas operaciones, mostrando ejemplos de URIs, métodos HTTP, posibles cuerpos de solicitud (payloads) y las respuestas esperadas. Los ejemplos se basarán en la estructura y convenciones presentadas en capítulos anteriores, utilizando JSON como formato de datos principal, siguiendo la preferencia de OData V4.
Leer Datos (GET)
La operación de lectura (Read) es la más común y se utiliza para recuperar información del servicio OData. Se realiza mediante solicitudes HTTP GET a la URI del recurso deseado.6
Leer un Conjunto de Entidades (Entity Set)
Para recuperar una colección de entidades, se realiza una solicitud GET a la URI del conjunto de entidades.
Método HTTP: GET
URI de Ejemplo: serviceRoot/People (Recupera la colección de entidades 'People') 26
Descripción: Solicita al servicio que devuelva una lista (o feed) de las entidades contenidas en el conjunto People.
Respuesta Típica (JSON): JSON { "@odata.context": "serviceRoot/$metadata#People", "@odata.nextLink": "serviceRoot/People?%24skiptoken=8", // Opcional, para paginación "value": }
La respuesta contiene un objeto JSON.
@odata.context indica el contexto de los metadatos para la colección.
@odata.nextLink (si existe) proporciona la URL para obtener la siguiente página de resultados (paginación del lado del servidor).
value es un array que contiene las instancias individuales de las entidades solicitadas, cada una con sus propiedades y metadatos OData (@odata.id, @odata.etag, etc.).26
Leer una Entidad Individual (por Clave)
Para recuperar una única entidad específica, se realiza una solicitud GET a la URI de la entidad, identificándola por su(s) clave(s).
Método HTTP: GET
URI de Ejemplo: serviceRoot/People('russellwhyte') (Recupera la entidad 'Person' con clave 'russellwhyte') 8
Descripción: Solicita al servicio la representación completa de la entidad Person cuya propiedad clave UserName es igual a 'russellwhyte'.
Respuesta Típica (JSON): JSON { "@odata.context": "serviceRoot/$metadata#People/$entity", "@odata.id": "serviceRoot/People('russellwhyte')", "@odata.etag": "W/\"...", "@odata.editLink": "serviceRoot/People('russellwhyte')", "UserName": "russellwhyte", "FirstName": "Russell", "LastName": "Whyte", //... otras propiedades }
La respuesta es un único objeto JSON que representa la entidad solicitada.
@odata.context indica el contexto de metadatos para una entidad individual.
Se incluyen las propiedades de la entidad y sus metadatos OData asociados.26
Si no se encuentra la entidad con la clave especificada, el servicio típicamente devuelve un código de estado HTTP 404 Not Found.
Leer una Propiedad Específica
Es posible solicitar el valor de una propiedad individual (primitiva o compleja) de una entidad específica.
Método HTTP: GET
URI de Ejemplo: serviceRoot/Airports('KSFO')/Name (Recupera la propiedad 'Name' de la entidad 'Airport' con clave 'KSFO') 26
Descripción: Solicita únicamente el valor de la propiedad Name de la entidad Airport especificada.
Respuesta Típica (JSON): JSON { "@odata.context": "serviceRoot/$metadata#Airports('KSFO')/Name", "value": "San Francisco International Airport" }
La respuesta contiene un objeto con el contexto de metadatos para la propiedad y la propiedad value con el valor solicitado.26
Leer el Valor Crudo de una Propiedad ($value)
Para obtener solo el valor de una propiedad primitiva, sin el formato JSON que lo envuelve, se puede añadir $value al final de la URI de la propiedad.
Método HTTP: GET
URI de Ejemplo: serviceRoot/Airports('KSFO')/Name/$value 16
Descripción: Solicita el valor crudo (raw) de la propiedad Name.
Respuesta Típica: San Francisco International Airport
La respuesta es directamente el valor de la propiedad, con un Content-Type apropiado (ej. text/plain para una cadena).26
Crear Datos (POST)
La operación de creación (Create) se utiliza para añadir una nueva entidad a un conjunto de entidades existente. Se realiza mediante una solicitud HTTP POST a la URI del conjunto de entidades.6
Método HTTP: POST
URI de Ejemplo: serviceRoot/People 26
Cabeceras:
Content-Type: Debe especificar el formato de los datos enviados en el cuerpo (ej. application/json).
Accept: (Opcional) Indica el formato preferido para la respuesta.
Cuerpo de la Solicitud (Payload - JSON): Contiene la representación de la nueva entidad a crear. Debe incluir las propiedades requeridas y, opcionalmente, el tipo de entidad usando @odata.type. JSON { "@odata.type": "Microsoft.OData.SampleService.Models.TripPin.Person", // Opcional si el tipo se puede inferir "UserName": "teresa", "FirstName": "Teresa", "LastName": "Gilbert", "Emails": ["teresa@example.com"], "Gender": "Female" //... otras propiedades iniciales } 26
Respuesta Típica (Éxito):
Código de Estado: 201 Created.26
Cabecera Location: Contiene la URI de la entidad recién creada (ej. serviceRoot/People('teresa')).26
Cabecera OData-EntityId: (Opcional) También puede contener la ID de la entidad creada.
Cuerpo de la Respuesta (Opcional): Puede contener la representación de la entidad creada, incluyendo propiedades generadas por el servidor (como IDs o timestamps).26
Respuesta Típica (Error):
Código de Estado: 4xx (ej. 400 Bad Request si los datos son inválidos) o 5xx (errores del servidor).
Cuerpo de la Respuesta: Generalmente contiene un objeto de error OData describiendo el problema.
Actualizar Datos (PUT / PATCH / MERGE)
La operación de actualización (Update) modifica una entidad existente. OData V4 utiliza principalmente PATCH para actualizaciones parciales y PUT para reemplazos completos. OData V2 a menudo usaba MERGE (similar a PATCH) o PUT.1
Método HTTP:
PATCH: Preferido para actualizaciones parciales (solo se envían las propiedades a modificar). Modifica la entidad existente con los valores proporcionados.1
PUT: Se utiliza para reemplazar completamente la entidad existente con la representación proporcionada en el cuerpo de la solicitud. Las propiedades no incluidas en la solicitud se establecerán a sus valores predeterminados o null.6
MERGE (Principalmente V2): Similar a PATCH, realiza una actualización parcial.1
URI de Ejemplo: serviceRoot/People('russellwhyte') (Se dirige a la entidad específica a actualizar) 26
Cabeceras:
Content-Type: Especifica el formato del payload (ej. application/json).
If-Match: Crucial para el control de concurrencia. Debe contener el valor ETag de la entidad que el cliente espera modificar. Si el ETag en el servidor no coincide, la actualización falla (ver Capítulo 5).39 Se puede usar If-Match: * para forzar la actualización independientemente de la versión actual, pero esto puede llevar a sobrescrituras no deseadas.39
Cuerpo de la Solicitud (Payload - JSON para PATCH): Contiene solo las propiedades que se desean modificar y sus nuevos valores. JSON { "Emails": } 26
Cuerpo de la Solicitud (Payload - JSON para PUT): Contiene la representación completa de la entidad con todos sus valores actualizados.
Respuesta Típica (Éxito):
Código de Estado: Generalmente 204 No Content (indica éxito pero no devuelve cuerpo).26 Ocasionalmente puede ser 200 OK si el servidor devuelve la entidad actualizada.
Cabecera ETag: (Opcional pero recomendado) Devuelve el nuevo valor ETag de la entidad actualizada.39
Respuesta Típica (Error):
Código de Estado:
404 Not Found: Si la entidad con la clave especificada no existe.
412 Precondition Failed: Si se proporcionó un If-Match y el ETag no coincide con la versión actual en el servidor.39
400 Bad Request: Si los datos del payload son inválidos.
5xx: Errores del servidor.
Cuerpo de la Respuesta: Objeto de error OData.
Eliminar Datos (DELETE)
La operación de eliminación (Delete) se utiliza para remover una entidad existente del servicio.
Método HTTP: DELETE 6
URI de Ejemplo: serviceRoot/People('vincentcalabrese') (Se dirige a la entidad específica a eliminar) 26
Cabeceras:
If-Match: Crucial para el control de concurrencia. Similar a Update, debe contener el ETag esperado de la entidad a eliminar para evitar borrar una versión modificada inadvertidamente.39 If-Match: * también es posible pero conlleva riesgos.39
Cuerpo de la Solicitud: Generalmente vacío.
Respuesta Típica (Éxito):
Código de Estado: 204 No Content.26
Respuesta Típica (Error):
Código de Estado:
404 Not Found: Si la entidad con la clave especificada no existe.
412 Precondition Failed: Si se proporcionó If-Match y el ETag no coincide.39
5xx: Errores del servidor.
Cuerpo de la Respuesta: Objeto de error OData (si aplica).
Comprender y utilizar correctamente estas operaciones CRUD y los métodos HTTP asociados es fundamental para interactuar eficazmente con cualquier servicio OData, permitiendo la gestión completa del ciclo de vida de los datos expuestos.
Last updated