Skip to content

lowered CrossRef R to Crossref - 'bout time! #134

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
wants to merge 1 commit into from
Closed

lowered CrossRef R to Crossref - 'bout time! #134

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
48 changes: 24 additions & 24 deletions rest_api.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
# CrossRef REST API
# Crossref Metadata API

## Version History

Expand Down Expand Up @@ -26,7 +26,7 @@
- v21: 2014-07-01, new `award.number` and `award.funder` relational filters.
- v22: 2014-07-16, changed title to more accurately reflect scope of API.
- v23, 2014-09-01, semantics of mutliple filters, dot filters
- v24, 2014-10-15, Added info on license of CrossRef metadata itself. Doh.
- v24, 2014-10-15, Added info on license of Crossref metadata itself. Doh.
- v25, 2015-05-06, Added link to issue tracker. Removed Warning section.
- v26, 2015-10-20, Added new filters - `from-created-date`, `until-created-date`, `affiliation`, `has-affiliation`, `assertion-group`, `assertion`, `article-number`, `alternative-id`
- v27, 2015-10-30, Added `cursor` parameter to `/works` resources
Expand All @@ -35,29 +35,29 @@

## Background

See the document, [CrossRef metadata best practice to support key performance indicators (KPIs) for funding agencies](https://github.com/CrossRef/rest-api-doc/blob/master/funder_kpi_metadata_best_practice.md), for background.
See the document, [Crossref metadata best practice to support key performance indicators (KPIs)](https://github.com/Crossref/rest-api-doc/blob/master/funder_kpi_metadata_best_practice.md), for background.

## Reporting issues

If you have suggestions or encounter problems with the API or the documentation, please report them on our [issue tracker](https://github.com/CrossRef/rest-api-doc/issues).
If you have suggestions or encounter problems with the API or the documentation, please report them on our [issue tracker](https://github.com/Crossref/rest-api-doc/issues).

If you have other queries, please contact us at:

![](http://labs.crossref.org/wp-content/uploads/2013/01/labs_email.png)

## License

CrossRef asserts no claims of ownership to individual items of bibliographic metadata and associated Digital Object Identifiers (DOIs) acquired through the use of the CrossRef Free Services. Individual items of bibliographic metadata and associated DOIs may be cached and incorporated into the user's content and systems. More information can be found [on our web site](http://www.crossref.org/requestaccount/).
Crossref asserts no claims of ownership to individual items of bibliographic metadata and associated Digital Object Identifiers (DOIs) acquired through the use of the Crossref Free Services. Individual items of bibliographic metadata and associated DOIs may be cached and incorporated into the user's content and systems. More information can be found [on our web site](http://www.crossref.org/requestaccount/).

## Overview

The API is generally RESTFUL and returns results in JSON.

The API will only work for CrossRef DOIs. You can test the registration agency for a DOI using the following route:
The API will only work for Crossref DOIs. You can test the registration agency for a DOI using the following route:

`http://api.crossref.org/works/{doi}/agency`

Testing the following CrossRef DOI:
Testing the following Crossref DOI:

`10.1037/0003-066X.59.1.29`

Expand All @@ -75,12 +75,12 @@ Will return the following result:
DOI: "10.1037/0003-066x.59.1.29",
agency: {
id: "crossref",
label: "CrossRef"
label: "Crossref"
}
}
}

If you use any of the API calls listed below with a non-CrossRef DOI, you will get a `404` HTTP status response. Typical agency IDs include `crossref`, `datacite`, `medra` and also `public` for test DOIs.
If you use any of the API calls listed below with a non-Crossref DOI, you will get a `404` HTTP status response. Typical agency IDs include `crossref`, `datacite`, `medra` and also `public` for test DOIs.

## Results Overview

Expand Down Expand Up @@ -123,7 +123,7 @@ If the API call includes a query, then the sort order will be by the relevance s


## Resource Components
Major resource components supported by the CrossRef API are:
Major resource components supported by the Crossref API are:

- works
- funders
Expand All @@ -138,21 +138,21 @@ These can be used alone like this
|:--------------|:----------------------------------|
| `/works` | returns a list of all works (journal articles, conference proceedings, books, components, etc), 20 per page
| `/funders` | returns a list of all funders in the [FundRef Registry](http://www.crossref.org/fundref/fundref_registry.html)
| `/members` | returns a list of all CrossRef members (mostly publishers) |
| `/members` | returns a list of all Crossref members (mostly publishers) |
| `/types` | returns a list of valid work types |
| `/licenses` | return a list of licenses applied to works in CrossRef metadata |
| `/journals` | return a list of journals in the CrossRef database |
| `/licenses` | return a list of licenses applied to works in Crossref metadata |
| `/journals` | return a list of journals in the Crossref database |


### Resource components and identifiers
Resource components can be used in conjunction with identifiers to retrieve the metadata for that identifier.

| resource | description |
|:----------------------------|:----------------------------------|
| `/works/{doi}` | returns metadata for the specified CrossRef DOI. |
| `/works/{doi}` | returns metadata for the specified Crossref DOI. |
| `/funders/{funder_id}` | returns metadata for specified funder **and** its suborganizations |
| `/prefixes/{owner_prefix}` | returns metadata for the DOI owner prefix |
| `/members/{member_id}` | returns metadata for a CrossRef member |
| `/members/{member_id}` | returns metadata for a Crossref member |
| `/types/{type_id}` | returns information about a metadata work type |
| `/journals/{issn}` | returns information about a journal with the given ISSN |

Expand All @@ -162,16 +162,16 @@ The works component can be appended to other resources.

| resource | description |
|:----------------------------|:----------------------------------|
| `/works/{doi}` | returns information about the specified CrossRef `DOI` |
| `/works/{doi}` | returns information about the specified Crossref `DOI` |
| `/funders/{funder_id}/works`| returns list of works associated with the specified `funder_id` |
| `/types/{type_id}/works` | returns list of works of type `type` |
| `/prefixes/{owner_prefix}/works` | returns list of works associated with specified `owner_prefix` |
| `/members/{member_id}/works` | returns list of works associated with a CrossRef member (deposited by a CrossRef member) |
| `/members/{member_id}/works` | returns list of works associated with a Crossref member (deposited by a Crossref member) |
| `/journals/{issn}/works` | returns a list of works in the given journal |

## Parameters

Parameters can be used to query, filter and control the results returned by the CrossRef API. They can be passed as normal URI parameters or as JSON in the body of the request.
Parameters can be used to query, filter and control the results returned by the Crossref API. They can be passed as normal URI parameters or as JSON in the body of the request.

| parameter | description |
|:-----------------------------|:----------------------------|
Expand Down Expand Up @@ -260,7 +260,7 @@ Filters allow you to narrow queries. All filter results are lists. The followin
| `has-funder` | | metadata which includes one or more funder entry |
| `funder` | `{funder_id}` | metadata which include the `{funder_id}` in FundRef data |
| `prefix` | `{owner_prefix}` | metadata belonging to a DOI owner prefix `{owner_prefix}` (e.g. `10.1016` ) |
| `member` | `{member_id}` | metadata belonging to a CrossRef member |
| `member` | `{member_id}` | metadata belonging to a Crossref member |
| `from-index-date` | `{date}` | metadata indexed since (inclusive) `{date}` |
| `until-index-date` | `{date}` | metadata indexed before (inclusive) `{date}` |
| `from-deposit-date` | `{date}` | metadata last (re)deposited since (inclusive) `{date}` |
Expand Down Expand Up @@ -327,13 +327,13 @@ Here we filter on works that have an award by the National Science Foundation th

### Notes on owner prefixes

The prefix of a CrossRef DOI does **NOT** indicate who currently owns the DOI. It only reflects who originally registered the DOI. CrossRef metadata has an **owner_prefix** element that records the current owner of the CrossRef DOI in question.
The prefix of a Crossref DOI does **NOT** indicate who currently owns the DOI. It only reflects who originally registered the DOI. Crossref metadata has an **owner_prefix** element that records the current owner of the Crossref DOI in question.

CrossRef also has member IDs for depositing organisations. A single member may control multiple owner prefixes, which in turn may control a number of DOIs. When looking at works published by a certain organisaton, member IDs and the member routes should be used.
Crossref also has member IDs for depositing organisations. A single member may control multiple owner prefixes, which in turn may control a number of DOIs. When looking at works published by a certain organisaton, member IDs and the member routes should be used.

### Notes on dates

Note that dates in filters should always be of the form `YYYY-MM-DD`, `YYYY-MM` or `YYYY`. Also note that date information in CrossRef metadata can often be incomplete. So, for example, a publisher may only include the year and month of publication for a journal article. For a monograph they might just include the year. In these cases the API selects the earliest possible date given the information provided. So, for instance, if the publisher only provided 2013-02 as the published date, then the date would be treated as 2013-02-01. Similarly, if the publisher only provided the year 2013 as the date, it would be treated at 2013-01-01.
Note that dates in filters should always be of the form `YYYY-MM-DD`, `YYYY-MM` or `YYYY`. Also note that date information in Crossref metadata can often be incomplete. So, for example, a publisher may only include the year and month of publication for a journal article. For a monograph they might just include the year. In these cases the API selects the earliest possible date given the information provided. So, for instance, if the publisher only provided 2013-02 as the published date, then the date would be treated as 2013-02-01. Similarly, if the publisher only provided the year 2013 as the date, it would be treated at 2013-01-01.

### Notes on incremental metadata updates

Expand Down Expand Up @@ -441,9 +441,9 @@ The API uses a semantic versioning scheme whereby the version number is divided
minor |
internal

**Major** version increments will are defined as releases that can break backwards compatibility. CrossRef will only commit to supporting the latest two major releases simultaneously and legacy major releases will be supported for no more than nine months. Exceptions to these rules may be made when major releases are required to ensure the security or stability of the system.
**Major** version increments will are defined as releases that can break backwards compatibility. Crossref will only commit to supporting the latest two major releases simultaneously and legacy major releases will be supported for no more than nine months. Exceptions to these rules may be made when major releases are required to ensure the security or stability of the system.

**Minor** version increments are defined as backwards compatible. There is no limit on the number of minor versions that can CrossRef can roll out. Note that client applications should not have dependencies on minor versions.
**Minor** version increments are defined as backwards compatible. There is no limit on the number of minor versions that can Crossref can roll out. Note that client applications should not have dependencies on minor versions.

**Internal** version increments are simply used to keep track of development versions of the API. They should never have any effect on client applications.

Expand Down