CrudApiPlugin

Artículo
03/07/2025

Simula una API CRUD con un almacén de datos en memoria. Envía respuestas JSON. Admite CORS para el uso entre dominios desde aplicaciones del lado cliente. Opcionalmente, simula las API CRUD protegidas con Microsoft Entra.

Definición de instancia del complemento

{
  "name": "CrudApiPlugin",
  "enabled": true,
  "pluginPath": "~appFolder/plugins/dev-proxy-plugins.dll",
  "configSection": "customersApi"
}

Ejemplo de configuración

{
  "customersApi": {
    "apiFile": "customers-api.json"
  }
}

Propiedades de configuración

Propiedad	Descripción
`apiFile`	Ruta de acceso al archivo que contiene la definición de la API CRUD

Opciones de línea de comandos

Ninguno

Ejemplo de archivo de API

A continuación se muestran varios ejemplos de archivos de API que definen una API CRUD para obtener información sobre los clientes.

API CRUD anónima

A continuación se muestra un ejemplo de un archivo de API que define una API CRUD anónima para obtener información sobre los clientes.

{
  "$schema": "https://raw.githubusercontent.com/dotnet/dev-proxy/main/schemas/v0.24.0/crudapiplugin.schema.json",
  "baseUrl": "https://api.contoso.com/v1/customers",
  "dataFile": "customers-data.json",
  "actions": [
    {
      "action": "getAll"
    },
    {
      "action": "getOne",
      "url": "/{customer-id}",
      "query": "$.[?(@.id == {customer-id})]"
    },
    {
      "action": "create"
    },
    {
      "action": "merge",
      "url": "/{customer-id}",
      "query": "$.[?(@.id == {customer-id})]"
    },
    {
      "action": "update",
      "url": "/{customer-id}",
      "query": "$.[?(@.id == {customer-id})]"
    },
    {
      "action": "delete",
      "url": "/{customer-id}",
      "query": "$.[?(@.id == {customer-id})]"
    }
  ]
}

API CRUD protegida con Microsoft Entra mediante un único ámbito

A continuación se muestra un ejemplo de un archivo de API que define una API CRUD para obtener información sobre los clientes protegidos con Microsoft Entra. Todas las acciones se protegen con un ámbito. CrudApiPlugin valida la audiencia del token, el emisor y el ámbito.

{
  "$schema": "https://raw.githubusercontent.com/dotnet/dev-proxy/main/schemas/v0.24.0/crudapiplugin.schema.json",
  "baseUrl": "https://api.contoso.com/v1/customers",
  "dataFile": "customers-data.json",
  "auth": "entra",
  "entraAuthConfig": {
    "audience": "https://api.contoso.com",
    "issuer": "https://login.microsoftonline.com/contoso.com",
    "scopes": ["api://contoso.com/user_impersonation"]
  },
  "actions": [
    {
      "action": "getAll"
    },
    {
      "action": "getOne",
      "url": "/{customer-id}",
      "query": "$.[?(@.id == {customer-id})]"
    },
    {
      "action": "create"
    },
    {
      "action": "merge",
      "url": "/{customer-id}",
      "query": "$.[?(@.id == {customer-id})]"
    },
    {
      "action": "update",
      "url": "/{customer-id}",
      "query": "$.[?(@.id == {customer-id})]"
    },
    {
      "action": "delete",
      "url": "/{customer-id}",
      "query": "$.[?(@.id == {customer-id})]"
    }
  ]
}

API CRUD protegida con Microsoft Entra mediante ámbitos específicos

A continuación se muestra un ejemplo de un archivo de API que define una API CRUD para obtener información sobre los clientes protegidos con Microsoft Entra. Las acciones se protegen con ámbitos específicos. CrudApiPlugin valida la audiencia del token, el emisor y el ámbito.

{
  "$schema": "https://raw.githubusercontent.com/dotnet/dev-proxy/main/schemas/v0.24.0/crudapiplugin.schema.json",
  "baseUrl": "https://api.contoso.com/v1/customers",
  "dataFile": "customers-data.json",
  "auth": "entra",
  "entraAuthConfig": {
    "audience": "https://api.contoso.com",
    "issuer": "https://login.microsoftonline.com/contoso.com"
  },
  "actions": [
    {
      "action": "getAll",
      "auth": "entra",
      "entraAuthConfig": {
        "scopes": ["api://contoso.com/customer.read"]
      }
    },
    {
      "action": "getOne",
      "url": "/{customer-id}",
      "query": "$.[?(@.id == {customer-id})]",
      "auth": "entra",
      "entraAuthConfig": {
        "scopes": ["api://contoso.com/customer.read"]
      }
    },
    {
      "action": "create",
      "auth": "entra",
      "entraAuthConfig": {
        "scopes": ["api://contoso.com/customer.write"]
      }
    },
    {
      "action": "merge",
      "url": "/{customer-id}",
      "query": "$.[?(@.id == {customer-id})]",
      "auth": "entra",
      "entraAuthConfig": {
        "scopes": ["api://contoso.com/customer.write"]
      }
    },
    {
      "action": "update",
      "url": "/{customer-id}",
      "query": "$.[?(@.id == {customer-id})]",
      "auth": "entra",
      "entraAuthConfig": {
        "scopes": ["api://contoso.com/customer.write"]
      }
    },
    {
      "action": "delete",
      "url": "/{customer-id}",
      "query": "$.[?(@.id == {customer-id})]",
      "auth": "entra",
      "entraAuthConfig": {
        "scopes": ["api://contoso.com/customer.write"]
      }
    }
  ]
}

Propiedades del archivo de API

Propiedad	Descripción	Obligatorio
`actions`	Lista de acciones que admite la API.	Sí
`auth`	Determina si la API está protegida o no. Valores permitidos: `none`, `entra`. `none` predeterminado	No
`baseUrl`	Dirección URL base donde el proxy de desarrollo expone la dirección URL. El proxy de desarrollo antepone la dirección URL base a las direcciones URL que defina en acciones.	Sí
`dataFile`	Ruta de acceso al archivo que contiene los datos de la API.	Sí
`entraAuthConfig`	Configuración de la autenticación de Microsoft Entra.	Sí, al configurar `auth` para `entra`

Puede hacer referencia a la dataFile mediante una ruta de acceso absoluta o relativa. El proxy de desarrollo resuelve rutas de acceso relativas relativamente al archivo de definición de API.

El dataFile debe definir una matriz JSON. La matriz puede estar vacía o puede contener un conjunto inicial de objetos.

Propiedades entraAuthConfig

Al configurar la propiedad auth para entra, debe definir la propiedad entraAuthConfig. Si no lo define, CrudApiPlugin muestra una advertencia y la API está disponible de forma anónima.

Puede definir entraAuthConfig en el archivo de API y en cada acción de API. Al definirlo en el archivo de API, se aplica a todas las acciones. Al definirlo en una acción, invalida la configuración del archivo de API para esta acción específica.

La propiedad entraAuthConfig tiene las siguientes propiedades.

Propiedad	Descripción	Obligatorio	Predeterminado
`audience`	Especifique la audiencia válida para el token. Cuando se especifica, CrudApiPlugin compara la audiencia del token con esta audiencia. Si son diferentes, CrudApiPlugin devuelve una respuesta 401 No autorizada.	No	Ninguno
`issuer`	Especifique el emisor de tokens válido. Cuando se especifica, CrudApiPlugin compara el emisor del token con este emisor. Si son diferentes, CrudApiPlugin devuelve una respuesta 401 No autorizada.	No	Ninguno
`scopes`	Especifique la matriz de ámbitos válidos. Cuando se especifica, CrudApiPlugin controla si alguno de los ámbitos está presente en el token. Si ninguno de los ámbitos está presente, CrudApiPlugin devuelve una respuesta 401 No autorizada.	No	Ninguno
`roles`	Especifique la matriz de roles válidos. Cuando se especifica, CrudApiPlugin controla si alguno de los roles está presente en el token. Si ninguno de los roles está presente, CrudApiPlugin devuelve una respuesta 401 No autorizada.	No	Ninguno
`validateLifetime`	Establézcalo en `true` de CrudApiPlugin para validar si el token no ha expirado. Cuando CrudApiPlugin detecta un token expirado, devuelve una respuesta 401 No autorizada.	No	`false`
`validateSigningKey`	Establézcalo en `true` para que CrudApiPlugin valide si el token es auténtico. Cuando CrudApiPlugin detecta un token con una firma no válida (por ejemplo, porque ha modificado el token manualmente), devuelve una respuesta 401 No autorizada.	No	`false`

Propiedades de acción

Cada acción de la lista de actions tiene las siguientes propiedades.

Propiedad	Descripción	Obligatorio	Predeterminado
`action`	Define cómo interactúa Dev Proxy con los datos. Valores posibles: `getAll`, `getOne`, `getMany`, `create`, `merge`, `update`, `delete`.	Sí	Ninguno
`auth`	Determina si la acción está protegida o no. Valores permitidos: `none`, `entra`.	No	`none`
`entraAuthConfig`	Configuración de la autenticación de Microsoft Entra.	Sí, al configurar `auth` para `entra`	Ninguno
`method`	Método HTTP que usa el proxy de desarrollo para exponer la acción.	No	Depende de la acción
`query`	Newtonsoft JSONPath consulta que usa el proxy de desarrollo para buscar los datos en el archivo de datos.	No	Vacío
`url`	Dirección URL en la que el proxy de desarrollo expone la acción. El proxy de desarrollo anexa la dirección URL a la dirección URL base.	No	Vacío

La dirección URL especificada en la propiedad url puede contener parámetros. Para definir parámetros, encapsula el nombre del parámetro en llaves, por ejemplo, {customer-id}. Al enrutar la solicitud, Dev Proxy reemplaza el parámetro por el valor de la dirección URL de la solicitud.

Puede usar el mismo parámetro en la consulta. Por ejemplo, si define el url como /customers/{customer-id} y el query como $.[?(@.id == {customer-id})], el proxy de desarrollo reemplaza el parámetro {customer-id} de la consulta por el valor de la dirección URL de la solicitud.

Importante

Dev Proxy implementa JSONPath en la propiedad query mediante Newtonsoft.Json. Hay algunas limitaciones para usarlo, como , solo admite comillas simples. Antes de enviar un problema, asegúrese de validar la consulta.

Cuando el complemento no encuentra los datos en el archivo de datos mediante la consulta, devuelve una respuesta 404 Not Found.

Cada tipo de acción tiene un método HTTP predeterminado. Puede invalidar el valor predeterminado especificando la propiedad method. Por ejemplo, el tipo de acción get tiene un método predeterminado de GET. Si quiere usar POST en su lugar, especifique la propiedad method como POST.

La matriz actions definió una colección de acciones que desea simular. Puede definir varias acciones para el mismo método HTTP y tipo de acción. Por ejemplo, puede definir dos acciones de getOne, una que recupera un cliente por su identificador y la otra por su dirección de correo electrónico. Asegúrese de definir direcciones URL únicas para cada acción.

Acciones

Dev Proxy admite las siguientes acciones para las API CRUD.

Acción	Descripción	Método predeterminado
`getAll`	Devuelve todos los elementos del archivo de datos.	`GET`
`getOne`	Devuelve un solo elemento del archivo de datos. Se produce un error cuando la consulta coincide con varios elementos.	`GET`
`getMany`	Devuelve varios elementos del archivo de datos. Devuelve una matriz vacía si la consulta no coincide con ningún elemento.	`GET`
`create`	Agrega un nuevo elemento a la colección de datos.	`POST`
`merge`	Combina los datos de la solicitud con los datos del archivo de datos.	`PATCH`
`update`	Reemplaza los datos del archivo de datos por los datos de la solicitud.	`PUT`
`delete`	Elimina el elemento del archivo de datos.	`DELETE`

Al crear un nuevo elemento mediante una acción de create, el complemento no valida su forma y lo agrega a la recopilación de datos as-is.

Ejemplo de archivo de datos

[
  {
    "id": 1,
    "name": "Contoso",
    "address": "4567 Main St Buffalo, NY 98052"
  },
  {
    "id": 2,
    "name": "Fabrikam",
    "address": "4567 Main St Buffalo, NY 98052"
  }
]

Compartir a través de