Utilice Insomnia para solicitudes de API

Introducción

Algunos encuentran que las declaraciones curl y la línea de comandos, que se utilizan para muchos de los ejemplos en la documentación de las API de nuestra plataforma, son difíciles e intimidantes. Para ellos, existen numerosas herramientas para enviar solicitudes HTTP a servicios basados en REST, que incluyen la mayoría de las API de Brightcove. Este documento le mostrará cómo utilizar una herramienta popular, la Insomnia aplicación.

Instalar en pc Insomnia

Obtener Insomnia de https://insomnia.rest . Insomnia se puede instalar en sistemas Mac, Linux o Windows.

Autenticación

Insomnia se puede utilizar para realizar solicitudes a cualquiera de las API RESTful de Brightcove. La mayoría de las API utilizan OAuth2 para la autenticación y veremos cómo configurarlo en Insomnia más adelante en este documento. Sin embargo, también puede usarlo para las API que no usan OAuth, simplemente configurando el encabezado apropiado.

Así es como se verá ese encabezado para las solicitudes con métodos de autenticación distintos de Oauth2:

Playback API

  BCOV-Policy: YOUR_POLICY_KEY

Live API

  X-API-KEY: YOUR_API_KEY

API de Zencoder

  Zencoder-Api-Key: YOUR_API_KEY

Obtenga las credenciales del cliente

Para trabajar con la mayoría de las API de Brightcove, necesitará las credenciales de cliente para la cuenta y las API que desea utilizar. Obtenga sus credenciales de cliente en Studio siguiendo las instrucciones en Administrar las credenciales de autenticación de API. En los pasos siguientes, haremos CMS API solicitudes usando Insomnia , por lo que sus credenciales deben tener al menos los siguientes permisos:

• Videos: Leer escribir

Puede agregar tantos permisos adicionales como desee para obtener credenciales que se podrán utilizar para una gama más amplia de solicitudes de API. También tenga en cuenta que puede obtener credenciales que funcionarán para varias cuentas si lo desea.

Utilizando Insomnia

Una vez que tenga sus credenciales de cliente, estará listo para comenzar a usar Insomnia . Insomnia hará mucho trabajo de configuración por usted si importa la especificación OpenAPI para la API de CMS, que ponemos a su disposición. Los pasos a continuación lo guiarán a través de la creación de algunos API de CMS solicitudes usando Insomnia.

configurar un Insomnia colección para la API de CMS

Obtenga la especificación de OpenAPI para la API de CMS

1. Abre el Referencia de la API de CMS.
2. Haga clic en el Descargar botón y guarde el openapi.yaml archivo en un lugar donde pueda encontrarlo de nuevo:

   

Importar la especificación OpenAPI en Insomnia

1. Lanzar el Insomnia aplicación.
2. Haga clic en el menú desplegable al lado Insomnia y seleccione Importación y exportación:

   

3. En el cuadro de diálogo que se abre, haga clic en Datos de importacion y seleccione Desde el archivo:

   

4. Selecciona el openapi.yaml archivo que descargó y luego elija si desea importar los datos al espacio de trabajo actual o crear uno nuevo. Cualquiera funcionará, pero recomendamos crear un nuevo espacio de trabajo para cada API:

   

5. A continuación, se le preguntará si desea importar los datos como una colección de solicitud o un documento de diseño. Escoger Solicitar colección:

   

6. Verá un cuadro de diálogo que confirma que se importaron los datos.
7. Haga clic en Tablero en la esquina superior izquierda para ver sus espacios de trabajo. Si creó un nuevo espacio de trabajo, verá que se muestra con el nombre apropiado:

   

8. Haga clic en el espacio de trabajo para abrirlo.
9. Verá una lista de carpetas que contienen los diversos grupos de solicitudes para la API de CMS y también un nuevo entorno OpenAPI:

   

Agregar variables al entorno

Este es un paso opcional, pero simplificará la configuración de la autenticación para solicitudes más adelante.

1. Clickea en el Env OpenAPI menú desplegable y seleccione Gestionar entornos:

   

2. Verá las variables de entorno que Insomnia creado a partir de la especificación OpenAPI en forma de JSON:

   

3. Agregue estas variables adicionales al JSON (consulte Obtener credenciales de cliente arriba en el client_id y client_secret):
   • "account_id": "your_account_id"
   • "client_id": "your_client_id"
   • "client_secret": "your_client_secret"
   • "access_token_url": "https://oauth.brightcove.com/v4/access_token"
4. Cuando haya terminado, el entorno JSON debería verse similar a esto:

   

5. Hacer clic Hecho en la esquina inferior derecha para salir del diálogo.

Configurar autenticación

Ahora estamos listos para configurar la autenticación para solicitudes de API.

1. Haga clic en el Videos carpeta y seleccione la Obtener videos:

   

2. Observe que la URL de la solicitud ya contiene dos variables. Si hace clic en estos, puede ver (y modificar) sus valores. base_url es generado automáticamente por Insomnio de la especificación OpenAPI. Si hace clic en account_id , debería encontrar que el valor coincide con lo que ingresó como variable de entorno en la sección anterior.
3. Haga clic en el Auth pestaña y la Menú desplegable de autenticación menú y seleccione OAuth 2.0:

   

4. Haga clic en el Tipo de subvención desplegable y seleccione Credenciales de cliente:

   

5. En el URL del token de acceso campo, comience a escribir "access_token_url"; verá el menú de autocompletar y seleccione su access_token_url Variable ambiental:

   

6. Repita el paso anterior para llenar el Identificación del cliente y Secreto del cliente campos con tu client_id y client_secret variables:

   

7. Desplácese hacia abajo para ver el Obtener token y haga clic en él. Asegúrese de ver el campo Token de acceso lleno con un token:

   

8. Hacer clic Obtener fichas para asegurarse de que esto funcione. Debería ver una respuesta como esta:

   

9. Ve a la Encabezamiento pestaña y eliminar la Autorización encabezado (la autenticación que acaba de configurar se hará cargo de la cabeza, esta la romperá):

   

Hacer una solicitud

Ahora estamos listos para hacer un Obtener videos solicitud.

1. Dado que este es un GET solicitud, todo lo que tiene que hacer es hacer clic Enviar.
2. Debería ver aparecer la respuesta JSON en el área Respuesta:

   

3. Tenga en cuenta que puede recuperar diferentes conjuntos de videos usando Consulta params. Haga clic en el Consulta pestaña para la solicitud, y verá que Insomnio lo ha poblado según la especificación de OpenAPI. Simplemente verifique los parámetros que desea usar y establezca los valores:

   

Enviar una POST solicitud

Ahora, enviaremos un POST solicitud con algunos datos. En este caso, crearemos un nuevo objeto de video usando la API de CMS. Empiece por seleccionar el Crear video solicitud en el Videos carpeta.

1. Repita todos los pasos del Configurar autenticación sección anterior para configurar la autenticación para esta nueva solicitud.
2. Esta solicitud requiere un cuerpo de solicitud, así que haga clic en la pestaña JSON e ingrese este código JSON para reemplazar el null:

   {
   	"name": "Insomnia Test"
   }

   

3. Hacer clic Enviar y debería ver el nuevo objeto de video devuelto en la respuesta.

Usando los generadores de código

Otra buena característica de Insomnio es que generará código para realizar solicitudes en muchos idiomas diferentes.

1. Desplácese y haga clic en el menú desplegable para una solicitud:

   

2. Seleccione Generar codigo del menú:

   

3. En el Generar código de cliente cuadro de diálogo que se abre, elija el idioma para el que desea el código:

   

4. Para muchos de los idiomas, también hay variantes que puede seleccionar que pueden ser más adecuadas para el tipo de aplicación que está creando:

   

5. También hay un botón útil para copiar el código a su portapapeles:

   

Conclusión

Ahora conoce los conceptos básicos del uso Insomnia para realizar solicitudes a las API de Brightcove. Tenga en cuenta que si elige actualizar su Insomnia cuenta a una cuenta de equipo, también puede sincronizar todas sus solicitudes y entornos y compartirlos con otros miembros del equipo.