You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: docs/get.md
+16-10Lines changed: 16 additions & 10 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -31,7 +31,7 @@ If you've ever signed into a site using Google or Facebook instead of your crede
31
31
###Get API credentials
32
32
API credentials consisting of a **client ID** and a **client secret** are needed in order to get Authenticated iDs and/or user permissions.
33
33
34
-
To get Authenticated iDs, you can use Public or Member API credentials. To get permission to read non-public information or add/update researchers' ORCID records, you'll need Member API credentials.
34
+
To get Authenticated iDs, you can use Public or Member API credentials. To get permission to read non-public information or add/update researchers' ORCID records, you'll need Member API credentials. For the rest of this tutorial, when referring to the API please assume that it is the Member API that is being referenced.
35
35
36
36
For this tutorial, please use your own sandbox API credentials:
37
37
@@ -56,34 +56,33 @@ To kick off the OAuth process, we'll need to create a special authorization URL
56
56
|**scope**| API action(s) you want to request permission for, from the list of [ORCID Scopes](https://members.orcid.org/api/oauth/orcid-scopes). | ```/authorize``` <br> ```/activities/update```
57
57
|**redirect_uri**| Page on your site that users will see after they complete the authorization process (must be on the list of allowed redirect URIs you specified when requesting your API credentials) |```https://developers.google.com/oauthplayground```|
58
58
59
-
To request permission to add/update activities (affiliations, funding, works, peer review items), our authorization URL will be:
60
-
Enter you own client ID where it says [APP-*****************]
3. After granting permission, you'll be redirected to the Google OAuth Playground. A 6-character code will appear at the end of the redirect URI in the browser address bar (and under the **Step 2** section at left)<br>
<imgsrc="../images/04-2_auth-code.png"width="400"alt="Browser address bar showing OAuth authorization code" />
78
77
79
-
###Exchange authorization code for access token & authenticated iD
78
+
###Exchange authorization code for access token and authenticated iD
80
79
Once you have an Authorization Code, you can exchange it for an Access Token and the Authenticated iD of the user who signed in, which you'll need in order to take the API action(s) you requested permission for. You need to store this securely and privately as it contains access tokens, normally you would store this in a database, for now you can store it in a text file on your computer.
81
80
82
81
In a real-world situation, this exchange would be done by your system, using a programming language such as PHP, Java, or Ruby on Rails. For this tutorial, we'll use Google OAuth Playground to simulate a web application.
83
82
84
83
1. Click the gear icon in the upper right corner to open the **OAuth 2.0 Configuration**<br>
2.Enter the following settings and click **Close**
85
+
2.Change the Oauth endpoints drop down to custom and enter the following settings and click **Close**
87
86
88
87
| Field | Value |
89
88
| ------| ------|
@@ -100,4 +99,11 @@ In a real-world situation, this exchange would be done by your system, using a p
100
99
4. Your Access Token and Authenticated iD will appear **Request/Response** section at right.<br>
101
100
<imgsrc="../images/04-3_token-response.png"width="600"alt="Google OAuth Playground json response for an access token request" /> <!--update with XML-->
102
101
102
+
103
+
**Save this token**
104
+
105
+
It is important to save the token you received in the step above as you can easily create any calls you need to make with it. If you loose the token you will have to go through the whole process above again.
106
+
103
107
Once you have gone through this process once and you have the token this is all that you need to do further api calls for this ORCID and for these permissions. If you want to make calls for another ORCID or you want to write to a record where before you have only read for example, then you will need to complete the process again and get a new token.
Now that we've got an Access Token, we can use it like a password to take the API actions we requested permission for.
2
1
3
-
In this section, we'll add an education affiliation to our Sandbox record. You can use the API to, POST (add), PUT (update), DELETE, or read any section of the record, the only things you need to change are the endpoints and the XML for each section. In the following example we are using the /education endpoint with the [correct XML](https://github.com/ORCID/ORCID-Source/blob/master/orcid-model/src/main/resources/record_2.1/samples/write_sample/education-2.1.xml) to add the information, but you can just as well add Employment or Works for example. See our [Github documentation](https://github.com/ORCID/ORCID-Source/blob/master/orcid-model/src/main/resources/record_2.1/README.md) for more example files and endpoints and the permissions you need for each.
2
+
In this section, we'll add an education affiliation to our Sandbox record. As you have seen you can use the API to GET (read) items on the record, you can also POST (add), PUT (update), DELETE, any section of the record, the only things you need to change are the endpoints and the XML for each section. In the following example we are using the /education endpoint with the [correct XML](https://github.com/ORCID/ORCID-Source/blob/master/orcid-model/src/main/resources/record_3.0/samples/write_sample/education-3.0.xml) to add the information, but you can just as well add Employment or Works for example. See our [Github documentation](https://github.com/ORCID/ORCID-Source/blob/master/orcid-model/src/main/resources/record_3.0/README.md) for more example files and endpoints and the permissions you need for each.
4
3
5
4
##Add an education affiliation
6
-
Still have that Google OAuth Playground window open? If so, continue with step 1 below. If not, go back and repeat the [Get an authorization code](/collect/#get-an-authorization-code) and [Exchange authorization code for an access token](/collect/#exchange-authorization-code-for-access-token-authenticated-id) steps from the previous section before moving on to the steps below.
5
+
Still have that Google OAuth Playground window open? If so, continue with step 1 below. If not, you have two options, If you saved your authorization token from earlier fill out the Oauth Playground window as you had it on [Read the record](read.md) or if not, go back and repeat the [Get an authorization code](get.md) and [Exchange authorization code for an access token](get.md#Exchange-authorization-code-for-access-token-and-authenticated-iD) steps from the previous section before moving on to the steps below. -->
7
6
8
7
1. Beneath **Step 3: Configure request to API**, set **HTTP Method** to **POST**.<br>
9
8
<imgsrc="../images/06-1_http-method-post.png"width="400"alt="Google OAuth Playground HTTP method set to POST" />
10
-
2. Click **Add headers**, enter the values below, then click **Add** and **Close**
9
+
2. Click **Add headers**, remove any previous headers and enter the values below, then click **Add** and **Close**
In a real-world situation, you may need to update a researcher's affiliation. In this section, we'll update our education affiliation to include an end date.
2
2
3
+
##A little about Put-codes
4
+
5
+
Put codes are short numeric codes that reference a particular item on the ORCID record. You use the put-code with the API calls to update, delete or read a particular item ( as opposed to a summary of items.)
6
+
To find out the put-code for a particular item we just need to read the record or a summary of the item we are interested in. The put-code for the item we want to modify will be returned in the response. See the XML below as an example.
7
+
8
+
In the example below we are updating a single education item.
3
9
##Update an education affiliation
4
10
5
-
1. In the **Request/Response** section at right, find the **put-code** for the education affiliation that you added in the previous section.<br>
11
+
1. First we need to get a **put code** for the work you just added so open a new Google Playground window and set it up following the first 4 steps from the [Read the record](read.md) .
12
+
13
+
2. This time in the Request URI field enter ```https://api.sandbox.orcid.org/v3.0/0000-XXXX-XXXX-XXXX/educations``` . Note that we have added 'educations' to the end of the URI and that it is plural. This means we are fetching a summary of all the education items on this record, not just one (we would put it singular and added / with a put code of the item at the end)
14
+
15
+
3. Hit the 'Send the request' and you should see something like the image below in the **Request/Response** section. Find the **put-code** for the education affiliation that you added in the previous section (it will be a different number to the one highlighted here).<br>
6
16
<imgsrc="../images/06-2_put-code.png"width="600"alt="Detailed view of Google OAuth Playground response for successful education affiliation POST request showing put-code" />
7
17
2. Change **HTTP Method** to **PUT**<br>
8
18
<imgsrc="../images/06-2_http-method-put.png"width="400"alt="Google OAuth Playground HTTP method set to PUT" />
9
19
3. Click **Add Headers** and make sure that ```accept``` and ```Content-type``` are both set to ```application/vnd.orcid+xml```<br>
10
20
<imgsrc="../images/06-2_put-headers.png"width="400"alt="Google OAuth Playground accept and Content-type header configuration" />
*Replace [ORCID ID] with the iD for your Sandbox record, format XXXX-XXXX-XXXX-XXXX and [PUT CODE] with the put-code for your education affiliation*<br>
14
24
<imgsrc="../images/06-2_request-uri.png"width="400"alt="Google OAuth Playground request URI configuration for updating an education affiliation" />
15
-
2.Click **Enter request body** (the XML for the affiliation you added in the previous step should appear).
25
+
2.Grab the XML from the end of the [POST](post.md) section again and the click **Enter request body** and paste it in.
16
26
3. Inside the ```<education:education``` tag, add ```put-code=[PUT CODE]```<br>
17
27
*Replace [PUT CODE] with the put-code for your education affiliation, ex ```<education:education put-code="26971"```*<br>
18
28
<imgsrc="../images/06-2_request-body-1.png"width="600"alt="Google OAuth Playground Request Body configuration for updating an education affiliation showing where to place put-code" />
19
-
4. Copy the affiliation end date XML at the end of this section and paste it beneath the ```</common:start-date>``` tag (and above the ```<education:organization>``` tag)<br>
29
+
4. Copy the Affiliation start and end date XML at the end of this section and paste it beneath the ```</common:role-title>``` tag (and above the ```<common:organization>``` tag)<br>
20
30
<imgsrc="../images/06-2_request-body-2.png"width="600"alt="Google OAuth Playground Request Body configuration for updating an education affiliation showing where to place end-date XML" />
21
31
5. Click **Close**.
22
32
6. Click **Send the Request**.
@@ -25,12 +35,17 @@ In a real-world situation, you may need to update a researcher's affiliation. In
25
35
8. Visit the **public view** of your Sandbox record at ```https://sandbox.orcid.org/[ORCID ID]``` to see your updated education affiliation.<br>
26
36
<imgsrc="../images/06-2_updated-affiliation.png"width="600"alt="ORCID record with updated education affiliation item" /><br>
* ORCID API users group [https://groups.google.com/group/orcid-api-users](https://groups.google.com/group/orcid-api-users)
4
4
* ORCID Support [support@orcid.org](mailto:support@orcid.org)
5
+
* API Tutorials Technical [https://github.com/ORCID/ORCID-Source/tree/master/orcid-api-web/tutorial](https://github.com/ORCID/ORCID-Source/tree/master/orcid-api-web/tutorial)
0 commit comments