# SHARE Push API You can access the holding area for the staging SHARE Push API [here](http://staging.osf.io/api/v1/share/data). You can register to be a provider for the SHARE staging Push API [here](https://staging-share-registration.osf.io/accounts/register/). If you're just getting started, give the staging push API a go - it's there for experimenting! You can access the SHARE Push API [here](http://osf.io/api/v1/share/data). Data listed here is in the "holding area" for SHARE pushed data. You can register to become a provider for the SHARE push API [here](https://share-registration.osf.io/accounts/register/) For more information about the SHARE schema, please see the [PUSH API Schema Detail Page](https://osf.io/api/v1/share/data/help/#!/SHARE/post_share_data). ### Using the Push API - The API will accept blobs of pre-formatted json data, within the field "jsonData." You can send as many of these blobs along as you like, just include them in a list when pushing. - Each document will be added as a single document in the [Push API holding area on production](https://osf.io/api/v1/share/data/) or [on staging](https://staging.osf.io/api/v1/share/data/). - Data will **not** automatically be harvested from the holding area into SHARE production OR staging until a member of the SHARE team has taken a look at the contents. - Once your provider is ready, it will begin being harvested into SHARE. There will be about a 15 minute delay between pushing harvested data and it showing up on [SHARE Production](http://osf.io/share) or [SHARE Staging](http://staging.osf.io/share). ### Sending Updates - Updates are stored as seperate documents on the holding area of the PUSH API. - Each document is labeled with a "status," either created or updated. - Updates are based on the First given "providerUri" in the list of providerUris. - To send an update, simply re-push the same document with the same first providerUri - That document will appear in the Push API staging area with a status of "updated." - The update will be reflected on the [SHARE API](http://osf.io/api/v1/share/search) after the document has been harvested. ### Deleting Documents - You can mark an item as "deleted" by adding a deleted status to the otherProperties field. This document will be marked as having a deleted status, and will be removed from the [SHARE API](http://osf.io/api/v1/share/search) after the document is harvested once again. See below for an example of sending a document with the status "deleted." ### SHARE Schema - See more about what can be included in the [SHARE Schema](https://github.com/CenterForOpenScience/SHARE-Schema). - Any of the fields in the SHARE schema can be included within the "jsonData" field. #### Required Fields within jsonData - **Title**: The title and any sub-titles of the resource. - **Contributors**: The people or organizations responsible for making contributions to an object. Each contributor is either a person or an organization. - **providerUpdatedDateTime**: The date and time the provider describing the object has been updated about either the creation or update of an object by its contributors. E.g., this may be the date a manuscript is published, but not necessarily the date the manuscript was written. - **Uris**: persistent HTTP URIs that describe your resource - **CanonicalUri**: The preferred persistent HTTP URI that represents the research object. *This should be repeated in exactly one other field in the uris object.* - **ProviderUris**: A list of the persistent HTTP URI that points to the object's record at the SHARE provider regardless of format. Here's a sample scenario of pushing data to SHARE. In these cases, we're going to use the same data. In order to do any of this, you will need to be authorized. To get login information and an authorization token, email us at [SHARE-support@osf.io](mailto:share-support@osf.io). ### Example data ``` { "jsonData": { "contributors": [ { "name": "Roger Movies Ebert", "sameAs": [ "https://osf.io/thing" ], "familyName": "Ebert", "givenName": "Roger", "additionalName": "Danger", "email": "rogerebert@example.com" }, { "name": "Roger Madness Ebert" } ], "languages": [ "eng" ], "description": "This is a thing", "providerUpdatedDateTime": "2014-12-12T00:00:00Z", "freeToRead": { "startDate": "2014-09-12", "endDate": "2014-10-12" }, "licenses": [ { "uri": "http://www.mitlicense.com", "startDate": "2014-10-12T00:00:00Z", "endDate": "2014-11-12T00:00:00Z" } ], "publisher": { "name": "Roger Ebert Inc", "email": "roger@example.com" }, "raw": "http://osf.io/raw/thisdocument/", "sponsorships": [ { "award": { "awardName": "Participation", "awardIdentifier": "http://example.com" }, "sponsor": { "sponsorName": "Orange", "sponsorIdentifier": "http://example.com/orange" } } ], "title": "Interesting research", "version": { "versionId": "someID" }, "uris": { "canonicalUri": "http://example.com/document1", "providerUris": [ "http://example.com/document1uri1", "http://example.com/document1uri2" ] } } } ``` ### Example Authorization Information For these examples, presume your: - User ID is `firstInitialLastname` - Password is `supersecurepassword123%` - Authorization token is `12345678901234567890`. ### Command line, with Auth Token To do this via the command-line, you can use `curl`. That command would look like: ``` curl https://staging.osf.io/api/v1/share/data/ -H 'Authorization: Token 12345678901234567890' -H "Content-Type: application/json" -X POST -d '{ "jsonData": { "contributors": [ { "name": "Roger Movies Ebert", "sameAs": [ "https://osf.io/thing" ], "familyName": "Ebert", "givenName": "Roger", "additionalName": "Danger", "email": "rogerebert@example.com" }, { "name": "Roger Madness Ebert" } ], "languages": [ "eng" ], "description": "This is a thing", "providerUpdatedDateTime": "2014-12-12T00:00:00Z", "freeToRead": { "startDate": "2014-09-12", "endDate": "2014-10-12" }, "licenses": [ { "uri": "http://www.mitlicense.com", "startDate": "2014-10-12T00:00:00Z", "endDate": "2014-11-12T00:00:00Z" } ], "publisher": { "name": "Roger Ebert Inc", "email": "roger@example.com" }, "raw": "http://osf.io/raw/thisdocument/", "sponsorships": [ { "award": { "awardName": "Participation", "awardIdentifier": "http://example.com" }, "sponsor": { "sponsorName": "Orange", "sponsorIdentifier": "http://example.com/orange" } } ], "title": "Interesting research", "version": { "versionId": "someID" }, "uris": {"canonicalUri": "http://example.com/document1", "providerUris": ["http://example.com/document1uri1", "http://example.com/document1uri2"]}}}' ``` ### Command line, with username and password ``` curl -u firstInitialLastname https://staging.osf.io/api/v1/share/data/ -H 'Authorization: Token 12345678901234567890' -H "Content-Type: application/json" -X POST -d '{ "jsonData": { "contributors": [ { "name": "Roger Movies Ebert", "sameAs": [ "https://osf.io/thing" ], "familyName": "Ebert", "givenName": "Roger", "additionalName": "Danger", "email": "rogerebert@example.com" }, { "name": "Roger Madness Ebert" } ], "languages": [ "eng" ], "description": "This is a thing", "providerUpdatedDateTime": "2014-12-12T00:00:00Z", "freeToRead": { "startDate": "2014-09-12", "endDate": "2014-10-12" }, "licenses": [ { "uri": "http://www.mitlicense.com", "startDate": "2014-10-12T00:00:00Z", "endDate": "2014-11-12T00:00:00Z" } ], "publisher": { "name": "Roger Ebert Inc", "email": "roger@example.com" }, "raw": "http://osf.io/raw/thisdocument/", "sponsorships": [ { "award": { "awardName": "Participation", "awardIdentifier": "http://example.com" }, "sponsor": { "sponsorName": "Orange", "sponsorIdentifier": "http://example.com/orange" } } ], "title": "Interesting research", "version": { "versionId": "someID" }, "uris": {"canonicalUri": "http://example.com/document1", "providerUris": ["http://example.com/document1uri1", "http://example.com/document1uri2"]}}}' ``` Then, curl should prompt you for a password. You can enter the password manually as well, but this is not reccomended as it will remain in the bash history in plaintext. To include the password, you'd replace your username (firstInitialLastname) with your username and password sperated by a colon (firstInitialLastname:supersecurepassword123%). ### Python common code For the python examples, the beginning of the files will be the same. Start out with ``` from __future__ import unicode_literals import requests valid = { "jsonData": { "contributors": [ { "name": "Roger Movies Ebert", "sameAs": [ "https://osf.io/thing" ], "familyName": "Ebert", "givenName": "Roger", "additionalName": "Danger", "email": "rogerebert@example.com" }, { "name": "Roger Madness Ebert" } ], "languages": [ "eng" ], "description": "This is a thing", "providerUpdatedDateTime": "2014-12-12T00:00:00Z", "freeToRead": { "startDate": "2014-09-12", "endDate": "2014-10-12" }, "licenses": [ { "uri": "http://www.mitlicense.com", "startDate": "2014-10-12T00:00:00Z", "endDate": "2014-11-12T00:00:00Z" } ], "publisher": { "name": "Roger Ebert Inc", "email": "roger@example.com" }, "sponsorships": [ { "award": { "awardName": "Participation", "awardIdentifier": "http://example.com" }, "sponsor": { "sponsorName": "Orange", "sponsorIdentifier": "http://example.com/orange" } } ], "title": "Interesting research", "version": { "versionId": "someID" }, "uris": { "canonicalUri": "http://example.com/document1", "providerUris": [ "http://example.com/document1uri1", "http://example.com/document1uri2" ] } } } route = 'https://staging.osf.io/api/v1/share/data/' list_data = [valid] ``` ### Python, with Auth token If you're using an Authorization token, follow the common code with: ``` token = 'Token 12345678901234567890' header= 'Authorization' x = requests.Session() x.headers.update({header: token}) response = x.post(route, json=list_data) ``` ### Python with User Name and Password If you are using a username and password, follow the common code with: ``` user_auth = ('firstInitialLastname', 'supersecurepassword123%') response = requests.post(route, json=list_data, auth=user_auth) ``` ### Deleting a Document If you wish to mark a document with the status "deleted," simply resend the document with the minimum information required, and make sure to have the same first element of your provider URIs, and a field included in the "otherProperties" section of a status "deleted." For example, if we would like to mark the above item as deleted in SHARE, we would push the following data, taking care to provide the same URL that we will use for the unique document ID, the first element in the ```providerUris``` list. ```json { "jsonData": { "contributors": [ { "familyName": "Ebert", "givenName": "Roger", "additionalName": "Danger", "email": "rogerebert@example.com" } ], "providerUpdatedDateTime": "2014-12-12T00:00:00Z", "title": "Interesting research", "uris": { "canonicalUri": "http://example.com/document1", "providerUris": [ "http://example.com/document1uri1" ] }, "otherProperties": [ { "name": "status", "properties": { "status": ["deleted"] } } ] } } ```