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.

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

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/

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

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.

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

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.

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.

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.