Track 1: Tutorial: Uso de la API - Presentación
Angel Montenegro
Este es un seminario/clase práctico para aquellos que son nuevos con la API. Se usarán herramientas como cURL and hurl.it para conectar con el registro ORCID, OAuth 2.0 para obtener los permisos de usuario, leer, añadir información y actualizar el registro ORCID.
PRESENTACION Plan de Desarrollo Municipal 2024-2027 AL CTP.pptx
tutorial guide using the api - 2015 espana seminario tecnico
1. Introducción de API
Índice
1. Acerca de las APIs de ORCID
2. Acceder a la API de miembros Sandbox
4. Obtener tokens de acceso
5. Leer un registro ORCID
6. Añadir trabajos a un registro ORCID
1. Acerca de las APIs de ORCID
1.1 Tipos y características de APIs de ORCID
ORCID ofrece APIs (Interfaces de Programación de Aplicaciones) que permiten que las
aplicaciones de internet interactúen con el registro ORCID. Algunas funciones API están
disponibles de forma gratuita para cualquiera; otras se proporcionan a organizaciones que apoyan a
ORCID con una suscripción de afiliación anual.
APIs operativas (Producción)
Estas APIs permiten a las organizaciones leer y escribir registros reales del registro operativo
ORCID.
• API pública: disponible de forma gratuita para cualquiera
• API de miembro básico: disponible para los miembros ORCID suscritos en el nivel básico
• API de miembro Premium: disponible para los miembros ORCID que se suscriben al nivel
Premium
APIs Sandbox (Prueba)
Estas APIs permiten a las organizaciones realizar pruebas sin afectar los registros del registro
operativo ORCID.
• API de miembro Sandbox: disponible de forma gratuita para cualquiera; simula las APIs de
miembros
• API público Sandbox: disponible de forma gratuita para cualquiera; simula la API pública
Para este taller, usaremos la API de miembro Sandbox. Para tener más información sobre las
diferencias entre las APIs, ver http://orcid.org/organizations/integrators/API
1.2 Tecnologías API de ORCID
Todas las APIs de ORCID se basan en el mismo conjunto de tecnologías.
• REST: Las APIs de ORCID son “RESTful”, que significa que usan llamadas HTTP
(transferencia de hipertexto) para transferir información.
2. Introducción de API
2
• OAuth: Las APIs ORCID usan el protocolo de autenticación OAuth 2.0 para otorgar
acceso a las aplicaciones de clientes a los registros ORCID de usuarios.
• XML/JSON: Las APIs ORCID soportan el intercambio de datos en formato XML o JSON
1.3 Herramientas API de ORCID
Para usar las APIs de ORCID necesitará las siguientes herramientas de software:
• Navegador Web: Firefox (v14+), Chrome (v21+), Internet Explorer (v9+), Safari (v6+)
• Conexión a Internet
• Editor de texto plano: TextEdit (Mac), Notepad ++ (Win), o su editor preferido de texto
plano
• Software capaz de realizar solicitudes HTTP:
o cURL: gratuita, aplicación de línea de comandos disponible para Mac o Windows en
http://curl.haxx.se/download.html (preinstalado en la mayoría de las versiones de
sistema operativo de Mac; al que se puede acceder en la aplicación Terminal)
o Herramientas online: tales como hurl.it o Google OAuth 2.0 Playground
Para este taller, usaremos la herramienta online Google OAuth 2.0 Playground
2. Acceder a la API de miembros Sandbox
Para usar la API de miembros Sandbox, necesitará:
• Credenciales de clientes Sandbox: una ID del cliente y Secreto de cliente, que permiten a
su sistema interactuar con la API
• Cuenta de usuario Sandbox: un registro de prueba ORCID que puede leer y escribir con
la API
2.1 Conseguir credenciales de cliente Sandbox
Las credenciales de cliente Sandbox le permiten a su sistema acceder a la Sandbox API de ORCID.
Las credenciales constan de:
• ID del cliente: un código alfanumérico que empieza por “APP-” que identifica su aplicación
(ej.: APP-V05T7FZU8MBVCXGN)
• Secreto de cliente: un código alfanumérico que actúa como su contraseña (ej.: a5e320d4-
093b-435f-b651-4dddc66351f5)
Las credenciales del cliente para las APIs de miembros son emitidas por ORCID. Para este taller,
hemos configurado las Credenciales del cliente Sandbox para usted por adelantado; en el futuro,
puede obtener Credenciales del cliente con el formulario de solicitud en
http://orcid.org/content/register-client-application
3. Introducción de API
3
2.2 Crear una cuenta de usuario Sandbox
Para intentar llamadas API, tales como leer un registro y añadir información al mismo, también
necesitará crear un registro prueba de ORCID en el Sandbox. Esto se puede realizar con la interfaz
de usuario, de manera similar al registro operativo de
ORCID.
1. Abrir un navegador de internet y navegar a
https://sandbox.orcid.org/signin
2. Haga clic en Registrarse para obtener una iD de
ORCID
3. Complete el formulario con un nombre, una
dirección de correo electrónico y una contraseña
4. Haga clic en la casilla “Acepto la política de
privacidad…” y haga clic en Registrarse.
5. Después de completar el proceso de registro, será
dirigido a su nuevo registro Sandbox de ORCID. Tome nota de la iD de16 dígitos de
ORCID para este registro, necesitará esto para realizar llamadas API más tarde durante el
taller.
3.0 Configuración de OAuth Playground
En una situación del mundo real, las interacciones API deberían ser completadas por su sistema con
un lenguaje de programación tales como PHP, Java, o Ruby on Rails. No obstante, para este taller
estaremos usando una herramienta tipo internet, OAuth 2.0 Playground de los desarrolladores de
Google.
¡IMPORTANTE! No use una dirección de correo electrónico real.
En su lugar, invente una dirección que acabe en @mailinator.com (el
prefijo puede ser cualquier cosa que le guste, ej.:
garcia@mailinator.com). El Sandbox está configurado para enviar
correos electrónicos solo a direcciones que acaban en mailinator.com,
un servicio gratuito de pruebas de correo electrónico. Puede
comprobar un buzón Mailinator visitando https://mailinator.com/
4. Introducción de API
4
Lo primero que necesitamos hacer es configurar OAuth 2.0 Playground para trabajar con la API de
ORCID.
1. Abra un navegador web y navegue a https://developers.google.com/oauthplayground
2. Haga clic en el icono de engranaje situado en la esquina superior derecha para abrir el
formulario de configuración.
3. En el formulario de configuración, introduzca la siguiente configuración:
OAuth flow Server-side
OAuth endpoints Custom
Authorization
endpoint
https://sandbox.orcid.org/oauth/authorize
Token endpoint https://api.sandbox.orcid.org/oauth/token
Access token
location
Authorization header w/Bearer prefix
OAuth Client ID Your assigned client id (ej.: APP-
F6TMYF419CVYMSNE)
OAuth Client
Secret
Your assigned client secret (ej.: f40a4c7d-
2306-44f1-b8af-a0e464e2bc37)
4. La pantalla de configuración debería ser similar a la imagen a la derecha. Después de que
haya introducido la configuración, haga clic en "Close" en la esquina inferior izquierda de la
pantalla de configuración.
4. Obtener tokens de acceso
Para leer/escribir en un registro ORCID a través de la API, primero debe obtener la autorización
del propietario del registro en el formato de un token de acceso, que se puede usar para acceder
al registro del usuario a través de la API. Este proceso de concesión de autorización se completa
con el protocolo OAuth 2 y consta de 3 pasos:
1. Obtener un Código de autorización
2. Intercambiar el código de autorización para un token de acceso
3. Usar el token de acceso para conseguir acceso al registro ORCID del usuario
http://orcid.uservoice.com/knowledgebase/articles/119676-tokens-through-3-legged-oauth-
authorization
5. Introducción de API
5
4.1 Conseguir un código de autorización
Para conseguir un Código de autorización, debe solicitar al usuario que se registre en su cuenta
ORCID y otorgar autorización a su aplicación. En una situación del mundo real, esto se hace con
una URL de autorización que usted construye. Sin embargo, con OAuth Playground, este paso se
realiza al configurar algunos ajustes adicionales y
hacer clic en un botón.
1. Primero, especificaremos la autorización
(“alcance”) que deseamos solicitar del
usuario, tal como la capacidad para leer y
añadir trabajos a su registro. Debajo de “Step
1: Select & authorize APIs” en el lado
izquierdo de la pantalla, escriba /orcid-
profile/read-limited en el recuadro de texto
(no seleccione ninguna de las opciones
incluidas arriba).
2. Aparecerá una pantalla de inicio de sesión ORCID,
que solicita que el usuario otorgue las autorizaciones
que ha introducido en los pasos previos. Cuando
aparezca esta pantalla, haga clic en “Sign In” e inicie
sesión en la cuenta de Sandbox de ORCID que acaba de crear.
3. Después de hacer clic en Authorize en la pantalla de inicio sesión de ORCID, se le enviará
de vuelta a OAuth 2.0
Playground y aparecerá un
código de 6 caracteres en el
campo Authorization Code
debajo de “Step 2: Exchange
authorization codes for
tokens”.
/orcid-profile/read-limited es un alcance que te permite leer un
registro de usuario ORCID, incluido cualquier elemento con una
configuración privada de “limited”. Para una lista de alcances usados
en API de ORCID, ver:
http://support.orcid.org/knowledgebase/articles/120162.
6. Introducción de API
6
4.2 Intercambiar el código de autorización para un token de acceso
Cuando tenga un Código de autorización, podrá intercambiarlo por un token de acceso, que le
permite leer/escribir en un registro de usuario ORCID. En una situación del mundo real, su sistema
realizaría este intercambio con un lenguaje de programación tal como PHP, Java o Ruby on Rails.
No obstante, con OAuth Playground, este paso se
realiza al hacer clic en un botón.
1. Debajo del campo Authorization Code,
haga clic en “Exchange authorization code
for tokens”.
2. El token aparecerá en el campo Access
Token.
3. Advierta en la sección Request/Response
del lado derecho de la pantalla, que se le
proporciona información adicional, tal
como el nombre y la ORCID iD del
usuario que otorgó autorización, la vida útil
del token (20 años) y el ámbito para el que
es válido el token.
5. Leer un registro ORCID
Ahora que tenemos un token de acceso, podemos usarlo para realizar acciones para las que
solicitamos autorización en el registro del usuario. En este caso, usamos el token de acceso para
leer el registro del usuario. En una situación del mundo real, su sistema realizaría este intercambio
con un lenguaje de programación tal como PHP, Java o Ruby on Rails. Sin embargo, con OAuth
Playground, este paso se realiza al configurar
algunos ajustes adicionales y hacer clic en un
botón.
1. Debajo del “Step 3: Configure request
to API” en el lado izquierdo de la
pantalla, configure el método HTTP a
GET
a. Haga clic en “Add headers” e
introduzca los siguientes valores:
b. Header name: Accept
c. Header value:
application/vnd.orcid+xml
7. Introducción de API
7
2. En el campo Request URI, introduzca https://api.sandbox.orcid.org/v1.2/[orcid-id]/orcid-
profile, y sustituya [orcid-id] con la ORCID iD del registro Sandbox que creó anteriormente
(ej.: https://api.sandbox.orcid.org/v1.2/0000-0002-1223-3173/orcid-profile)
3. Deje los campos Request Body y Content-Type en blanco, y haga clic en Send the Request.
4. El XML para el registro ORCID que solicitó aparecerá en la sección Request/Response del
lado derecho de la pantalla.
6. Añadir trabajos a un registro ORCID
Además de leer información de los registros ORCID, la API de miembro ORCID también se
puede usar para añadir información a los registros ORCID. Después, añadiremos un trabajo a
nuestro registro ORCID.
6.1 Conseguir un código de autorización
Aunque la API de ORCID le permite solicitar un token de acceso para múltiples alcances de una
vez, OAuth 2.0 Playground no le permite hacer esto, así que primero necesitamos generar un
nuevo token de acceso.
1. Debajo de “Step 1: Select & authorize APIs” en el
lado izquierdo de la pantalla, escriba /orcid-
works/create en el recuadro de texto (no
seleccione ninguna de las opciones incluidas arriba).
2. Haga clic en Authorize APIs
3. Aparecerá una pantalla de inicio de sesión ORCID;
haga clic en “Sign In” y regístrese en su cuenta
Sandbox ORCID.
4. Después de hacer clic en Authorize en la
pantalla de inicio sesión de ORCID, se le
enviará de vuelta a OAuth 2.0 Playground y
aparecerá un código de 6 caracteres en el
campo Authorization Code.
8. Introducción de API
8
6.2 Intercambiar el código de autorización para un token de acceso
1. Debajo del campo Authorization Code,
haga clic en “Exchange authorization code
for tokens”.
2. El token aparecerá en el campo Access
Token.
6.3 Publicar el trabajo en el registro ORCID
1. Debajo de “Step 3: Configure request to API”, configure Método HTTP a PUBLICAR
2. Haga clic en “Add headers” e introduzca los siguientes valores:
a. Header name: Accept
b. Header value: application/vnd.orcid+xml
3. Haga clic en “Add” para añadir otra cabecera e introduzca los valores siguientes:
a. Header name: Content-type
b. Header value: application/vnd.orcid+xml
4. Haga clic en "Add” de nuevo, después haga clic en “Close”.
5. En el campo Request URI, introduzca https://api.sandbox.orcid.org/v1.2/[orcid-id]/orcid-
works, y sustituya [orcid-id] con la ORCID iD del registro Sandbox que creó anteriormente
(ej.: https://api.sandbox.orcid.org/v1.2/0000-0002-1223-3173/orcid-works)
6. Haga clic en “Enter request body” - en este espacio introducirá el XML para los trabajos
que desea añadir. Por simplicidad, hemos preparado el XML para usted en el archivo
sample-work.xml.
7. Abra sample-work.xml en un editor de texto simple (tal como TextEdit o Notepad ++) y
copie su contenido.
9. Introducción de API
9
8. Pegue el contenido copiado en el cuadro de texto de Request Body y haga clic en
“Cerrar”.
9. Haga clic en “Send the Request”
10. Los resultados aparecerán en la sección Request/Response en el lado derecho de la
pantalla. Si ve “HTTP/1.1 201 Created” en la respuesta, ¡el trabajo se ha publicado
correctamente!
11. Visite la vista pública de su registro de Sandbox en http://sandbox.orcid.org/[Su iD de
sandbox] para ver el trabajo que ha añadido en la interfaz de usuario.