-
Notifications
You must be signed in to change notification settings - Fork 3
SUL Pub API Documentation
Note: This documentation can be used until an official OpenAPI spec is available (see https://github.com/sul-dlss/sul_pub/issues/1413)
The first section shows the JSON response which will be returned for the API calls that request publications. For API calls that return multiple publications, you will receive an array of BibJSON objects.
The second section shows the the available endpoints. Note that the endpoints shown below are appended to the base URL of the API being called (which depends on the environment, e.g. prod vs UAT). Authorization for all endpoints is via private API passed in the header with each request. You will get a 401 unauthorized if you leave off the API key or a 403 forbidden if it is not correct for the environment you are using. The API is only available to Stanford consumers and restricted to the campus network.
The "pub_hash" data structure for a single publication is BibJSON, with the schema shown here: https://github.com/sul-dlss/sul_pub/blob/main/pub_hash_schema.yml
Here is an example single publication response matching the schema above. See the schema above for a description of the available fields.
{
"abstract_restricted": "Nitrous oxide (N2O) is a potent greenhouse gas and an ozone destroying substance. Yet, clear step-by-step protocols to measure N2O transformation rates in freshwater and marine environments are still lacking, challenging inter-comparability efforts. Here we present detailed protocols currently used by leading experts in the field to measure water-column N2O production and consumption rates in both marine and other aquatic environments. We present example 15N-tracer incubation experiments in marine environments as well as templates to calculate both N2O production and consumption rates. We discuss important considerations and recommendations regarding (1) precautions to prevent oxygen (O2) contamination during low-oxygen and anoxic incubations, (2) preferred bottles and stoppers, (3) procedures for 15Ntracer addition, and (4) the choice of a fixative. We finally discuss data reporting and archiving. We expect these protocols will make 15N-labeled N2O transformation rate measurements more accessible to the wider community and facilitate future inter-comparison between different laboratories.",
"author": [
{
"display_name": "Bourbonnais, Annie",
"first_name": "Annie",
"last_name": "Bourbonnais",
"full_name": "Bourbonnais, Annie",
"role": "author",
"name": "Bourbonnais,Annie,"
},
{
"display_name": "Frey, Claudia",
"first_name": "Claudia",
"last_name": "Frey",
"full_name": "Frey, Claudia",
"role": "author",
"name": "Frey,Claudia,"
},
{
"display_name": "Sun, Xin",
"first_name": "Xin",
"last_name": "Sun",
"full_name": "Sun, Xin",
"role": "author",
"name": "Sun,Xin,"
},
{
"display_name": "Bristow, Laura A.",
"first_name": "Laura",
"last_name": "Bristow",
"full_name": "Bristow, Laura A.",
"role": "author",
"middle_name": "A",
"name": "Bristow,Laura,A"
},
{
"display_name": "Jayakumar, Amal",
"first_name": "Amal",
"last_name": "Jayakumar",
"full_name": "Jayakumar, Amal",
"role": "author",
"name": "Jayakumar,Amal,"
},
{
"display_name": "Ostrom, Nathaniel E.",
"first_name": "Nathaniel",
"last_name": "Ostrom",
"full_name": "Ostrom, Nathaniel E.",
"role": "author",
"middle_name": "E",
"name": "Ostrom,Nathaniel,E"
},
{
"display_name": "Casciotti, Karen L.",
"first_name": "Karen",
"last_name": "Casciotti",
"full_name": "Casciotti, Karen L.",
"role": "author",
"middle_name": "L",
"name": "Casciotti,Karen,L"
},
{
"display_name": "Ward, Bess B.",
"first_name": "Bess",
"last_name": "Ward",
"full_name": "Ward, Bess B.",
"role": "author",
"middle_name": "B",
"name": "Ward,Bess,B"
}
],
"authorcount": 8,
"publisher": "FRONTIERS MEDIA SA",
"city": "LAUSANNE",
"stateprovince": null,
"country": null,
"year": "2021",
"date": "2021-04-22",
"title": "Protocols for Assessing Transformation Rates of Nitrous Oxide in the Water Column",
"journal": {
"name": "FRONTIERS IN MARINE SCIENCE",
"volume": "8",
"identifier": [
{
"type": "eissn",
"id": "2296-7745",
"url": "http://searchworks.stanford.edu/?search_field=advanced&number=2296-7745"
}
]
},
"documenttypes_sw": [
"Article",
"Journal"
],
"documentcategory_sw": "Journal",
"type": "article",
"identifier": [
{
"type": "doi",
"id": "10.3389/fmars.2021.611937",
"url": "https://doi.org/10.3389/fmars.2021.611937"
},
{
"type": "eissn",
"id": "2296-7745",
"url": "http://searchworks.stanford.edu/?search_field=advanced&number=2296-7745"
},
{
"type": "WosItemID",
"id": "000647466600001",
"url": "https://ws.isiknowledge.com/cps/openurl/service?url_ver=Z39.88-2004&rft_id=info:ut/000647466600001"
},
{
"type": "WosUID",
"id": "WOS:000647466600001"
},
{
"type": "SULPubId",
"id": "812414",
"url": "http://sulcap.stanford.edu/publications/812414"
}
],
"provenance": "wos",
"wos_uid": "WOS:000647466600001",
"doi": "10.3389/fmars.2021.611937",
"eissn": "2296-7745",
"wos_item_id": "000647466600001",
"apa_citation": "Bourbonnais, A., Frey, C., Sun, X., Bristow, L. A., Jayakumar, A., Ostrom, N. E., … Ward, B. B. (2021). Protocols for Assessing Transformation Rates of Nitrous Oxide in the Water Column. <i>FRONTIERS IN MARINE SCIENCE</i>, <i>8</i>.",
"mla_citation": "Bourbonnais, Annie et al. “Protocols for Assessing Transformation Rates of Nitrous Oxide in the Water Column.” <i>FRONTIERS IN MARINE SCIENCE</i> 8 (2021): n. pag. Print.",
"chicago_citation": "Bourbonnais, Annie, Claudia Frey, Xin Sun, Laura A. Bristow, Amal Jayakumar, et al. 2021. “Protocols for Assessing Transformation Rates of Nitrous Oxide in the Water Column.” <i>FRONTIERS IN MARINE SCIENCE</i> 8. FRONTIERS MEDIA SA.",
"authorship": [
{
"cap_profile_id": 45761,
"sul_author_id": 30464,
"status": "new",
"visibility": "public",
"featured": false
}
],
"last_updated": "2021-05-27 11:40:42 UTC",
"sulpubid": "812414"
}
Send a cap_profile_id in the URL:
POST /authors/:cap_profile_id/harvest.json
Response is plain text indicating success or error, http code 201 for success or 500 for error.
Create or update an authorship record, i.e. an association between an existing publication and an existing author.
The POST operation will create or update an existing record. Authors can be identified using cap_profile_id or sul_author_id (primary key on our author table). Publications can be identified using sul_pub_id (primary key on our publications table), pmid, sw_id, or wos_uid. At least one author identifier and one publication identifier are required. Example JSON shown below with allowed values for the attributes. Note you must send all attributes with this request (even if using to only update one attribute). Attributes shown with values in brackets [ ] below indicate the allowed values for the attributes separated by a pipe |.
POST /authorship.json
Request data:
{"cap_profile_id":"cap_profile_id","featured":[true|false],"status":"[approved|denied]","visibility":"[public|private]","sul_pub_id":"sul_pub_id"}
Response is code 201 for success, 400 or 406 for bad parameters or 500 for error.
Update an authorship record, i.e. an association between an existing publication and an existing author.
The PUT or PATCH request option allows partial (or full) attribute updates on an existing contribution (association between a publication and an author). It will not create any new authors, publication or contributions. You send a PATCH request with JSON data. It requires a sul_pub_id (primary key on our publication table) to identify an existing publication (it does not accept a pmid or sw_id). It accepts sul_author_id (primary key on our author table) or cap_profile_id to identify an existing author. If it can find an existing contribution for the given author and publication, it will update any of the contribution attributes: featured, status, or visibility. Any or all of these can be included in the JSON payload. Any attributes that are not given should not be changed. It thus allows partial updating for an existing contribution record. Example JSON shown below with allowed values for the attributes.
PUT OR PATCH /authorship.json
Request data:
{"cap_profile_id":"cap_profile_id","featured":[true|false],"status":"[approved|denied]","visibility":"[public|private]","sul_pub_id":"sul_pub_id"}
Response is code 202 for success, 400 or 406 for bad parameters, or 500 for error.
Retrieve publications, either as JSON or CSV. The format of the response is determined by the extension of the URL.
JSON:
GET /publications.json
CSV:
GET /publications.csv
Available query string parameters:
-
capProfileId=X- the cap_profile_id of the author to restrict publications to -
page=X- the page number of results to return (defaults to 1) -
per=X- the number of results per page to return (defaults to 1000) -
capActive=true- restrict to only active CAP authors -
changedSince=YYYY-MM-DD- restrict to only publications created/updated since that date
For example:
GET /publications.json?capProfileId=1&changedSince=2018-01-01 # publications on cap_profile_id 1 since Jan 1, 2018
Returns a JSON data structure that includes a metadata element shown below and a records element which is an array of publication BibJSON (with the schema shown at the top of the page). The metadata elements includes:
-
_created- current date -
description- unused -
format- BibJSON -
license- unused -
page- the current page of results -
per_page- the number returned per page -
query- the query sent -
records- total number of results on this page (not total for the query)
If there is more than one pages of results (i.e if records == per_page), you will need to keep paging until you get a records == 0.
{
"metadata": {
"_created": "2021-11-16T16:20:31Z",
"description": null,
"format": "BibJSON",
"license": "some licence",
"page": 1,
"per_page": 1000,
"query": "/publications.json?changedSince=2021-01-01T00:00:00Z&capProfileId=45761",
"records": "104"
},
"records": [
{
Publication 1 BibJSON
},
{
Publication 2 BibJSON
}
]
}
GET /publications/:sul_pub_id
Returns a single publication BibJSON element for the given sul_pub_id, with code 200. There is no metadata element.
Returns a 404 for publication not found, or 500 for error.
POST /publications
Note that you must include the authorship block, which connects this publication to a valid author via the cap_profile_id or sul_author_id. Publications can be identified using sul_pub_id (primary key on our publications table), pmid, sw_id, or wos_uid. At least one author identifier and one publication identifier are required.
Request should be a valid BibJSON record, for example:
{ "type":"book",
"title":"some title",
"year":"1938",
"issn":"32242424",
"pages":"34-56",
"author":[
{"name":"Jackson Joe"}
],
"authorship":
[
{"cap_profile_id":1,
"sul_author_id": 1,
"status":"approved",
"visibility":"[public|private]",
"featured":[true|false],
"additionalProperties": {}
}
]
}
Response is code 201 for success, 400 or 406 for bad parameters or 500 for error.
This updates an existing manually created publication - note that if you try to update a sul_pub_id for a publication whose provenance is not CAP (i.e. it was harvested, not manually created), you get a 403 forbidden response. You must pass in the sul_pub_id for the publication in the request URL.
PUT OR PATCH /publications/:sul_pub_id
The request data is exactly the same as for creating a new manual publication, just pass in any data to be updated.
Response is 202 for success, 403 for not allowed, 404 for publication not found, 406 for bad data, 410 for publication deleted, or 500 for error.
IMPORTANT: There is not a current use case for this. The publication will be marked as deleted in the database, but the data remains in the database. Deleted publications are still returned when requesting publications for authors.
DELETE /publications/:sul_pub_id
Response is 200 for success, 404 for publication not found, 410 for publication already deleted.
Used to search for publications, either currently in sul-pub or at the Web of Science or Pubmed Central. Pass in a title, a DOI or a PMID as a search parameter in the URL of the request using the appropriated query string parameter as shown below. It returns JSON with a metadata element and a records array of BibJSON, exactly the same format as the Return Publications endpoint described above. Note that this may return some publications which already exist on Profiles or publications which do not yet exist on Profiles (but are found in the Web of Science or Pubmed databases). In the case of existing Profile publications, the authorship block in the BibJSON will be returned, else it will be blank (as there is no established Profiles authorships in these cases)
Search by title:
GET /publications/sourcelookup.json?title=TITLE
Search by DOI:
GET /publications/sourcelookup.json?doi=DOI
Search by PMID:
GET /publications/sourcelookup.json?pmid=PMID