From ff245cec77b7065a60a895f1687476f98ec4b976 Mon Sep 17 00:00:00 2001 From: Geoffrey Bilder Date: Thu, 12 Dec 2013 09:52:32 +0000 Subject: [PATCH 001/219] generate html for v11 --- funder_kpi_api.html | 18 ++++++++-------- funder_kpi_metadata_best_practice.html | 30 ++++++++++++++++++++------ 2 files changed, 32 insertions(+), 16 deletions(-) diff --git a/funder_kpi_api.html b/funder_kpi_api.html index 2119984..1b0eed0 100644 --- a/funder_kpi_api.html +++ b/funder_kpi_api.html @@ -402,7 +402,7 @@

Parameters

offset={#} - page offset + result offset sample={#} @@ -494,19 +494,19 @@

Filter Names

metadata that includes any <license_ref> elements. - license.uri - {uri} - metadata where <license_ref> value equals {uri} + license.url + {url} + metadata where <license_ref> value equals {url} - license.content-version + license.version {string} metadata where the <license_ref>’s applies_to attribute is {string} - license.max-embargo-days + license.delay {integer} - metadata where difference between publication date and the <license_ref>’s start_date attribute is <= {integer} + metadata where difference between publication date and the <license_ref>’s start_date attribute is <= {integer} (in days) has-full-text @@ -514,12 +514,12 @@

Filter Names

metadata that includes any full text <resource> elements. - fulltext.content-version + full-text.version {string} metadata where <resource> element’s content_version attribute is {string}. - fulltext.content-type + full-text.type {mime_type} metadata where <resource> element’s content_type attribute is {mime_type} (e.g. application/pdf). diff --git a/funder_kpi_metadata_best_practice.html b/funder_kpi_metadata_best_practice.html index 974badf..0b1f961 100644 --- a/funder_kpi_metadata_best_practice.html +++ b/funder_kpi_metadata_best_practice.html @@ -181,6 +181,7 @@

Version History

  • V08: 2013–11–04, Added FAQ about schema interpretation and usage
  • V09: 2013–12–02, Added XML deposit examples
  • v10: 2013–12–03, Updated <free-to-read/> element documentation to reflect latest NISO work. Added information about licensing CrossRef metadata to FAQ (hint, no license required for free APIs). Added labs email address. Changed formatting.
    • +
  • v11: 2013–12–11, Added third party archive arrangements section. Updated examples to include archive locations.

    • Warning

    @@ -234,6 +235,7 @@

    Summary

  • Publishers should record full text links to representations of the document that are made available for TDM. These may be the same or different to the “readable” versions of the document pointed to above.
  • Where they are recording multiple versions of the document (e.g. AM & VOR), the publisher should map licensing information to the specific resource versions.
  • Publishers should record full text links to archived versions of the document identified by the CrossRef DOI.
    • +
  • Publishers should record archive arrangements made with third party archiving organizations where the document identified by the CrossRef DOI is archived with the third party.

    • In order to enhance the utility of CrossRef metadata to agencies and in order to enable more sophisticated agency/publisher KPIs:

    @@ -337,7 +339,7 @@

    Recording

    Note also that the publisher could theoretically choose only to deposit <resource> elements for full text representations once an embargo has ended. However, this approach may prove fraught, as any mistakes or delays in the redeposit process might lead the funding agency to believe that the publisher has not made the relevant content accessible at the end of the embargo period.

    -

    Further detail on using the <resource> element for recording links to full text can be found on the Prospect support site and in the CrossRef deposit schema documentation for the <collection> and <resource> elements.

    +

    Further detail on using the <resource> element for recording links to full text can be found on the Prospect support site and in the CrossRef deposit schema documentation for the <collection> and <resource> elements.

    Different licenses for different versions of the content

    @@ -383,7 +385,7 @@

    Different licenses fo <resource content_version="tdm">http://www.psychoceramics.org/fulltext/tdm/10.5555/12345678.xml</resource> -

    Detailed information on recording licensing information in CrossRef metadata can be found in the CrossRef schema documentation for the <license_ref> element.

    +

    Detailed information on recording licensing information in CrossRef metadata can be found in the CrossRef schema documentation for the <license_ref> element.

    “Libre” vs “Gratis”

    @@ -424,17 +426,31 @@

    “Libre” vs “Gratis”

    <license_ref>http://creativecommons.org/licenses/by/3.0/deed.en_US</license_ref> +

    Recording third party archive arrangements

    + +

    Funders may be concerned that publisher links to full-text content will become unavailable in exceptional circumstances. They may stipulate that content is archived with a third party archiving organization, and may even suggest a list of acceptable archive organizations with which documents should be archived.

    + +

    Publishers can record the archive arrangement or archive intention of a document using the <archive_locations> element in CrossRef deposit metadata. Any number of archive locations can be specified, for example a document may be archived with both Portico and CLOCKSS:

    + +
    <archive_locations>
+  <archive name="CLOCKSS"/>
+  <archive name="Portico"/>
+</archive_locations>
+
    + +

    CrossRef maintains a vocabulary of archive locations within the CrossRef deposit schema. The latest list of possible archive location values can be found in the documentation for the <archive> element .

    +

    Bonus points

    The more metadata that publishers record for publications arising from agency funded research, the more useful that metadata will be to said agencies and the more value they will see from publishers. Where as the above sections details metadata elements that agencies will expect in order to be able to compile basic KPIs and offer portal services, additional metadata will allow agencies to create even more sophisticated KPIs and services. As such, publishers should seriously consider depositing the following additional metadata elements in their CrossRef deposits.

    Distributing standard bibliographic metadata

    -

    Metadata deposited to CrossRef is made available freely via numerous CrossRef query APIs. However all deposited metadata is subject to opt-outs in the case of bulk distribution APIs and data dumps. In order to make sure that bibliographic metadata for publications arising from agency funding is maximally available, publishers should consider setting the value of the <metadata_distribution_opts> element for DOIs to any. Further details can be found in CrossRef’s schema documentation for the <metadata_distribution_opts> element.

    +

    Metadata deposited to CrossRef is made available freely via numerous CrossRef query APIs. However all deposited metadata is subject to opt-outs in the case of bulk distribution APIs and data dumps. In order to make sure that bibliographic metadata for publications arising from agency funding is maximally available, publishers should consider setting the value of the <metadata_distribution_opts> element for DOIs to any. Further details can be found in CrossRef’s schema documentation for the <metadata_distribution_opts> element.

    Distributing references

    -

    References made in publications arising from agency funding can provide agencies with an overview of what literature is considered important in the fields that they fund. Many publishers deposit references to CrossRef as part of their participation CrossRef’s CitedBy service. However, participation in CitedBy does not automatically make references available via CrossRef’s standard APIs. In order for publishers to distribute references along with standard bibliographic metadata, publishers need to set the <reference_distribution_opt> element to any for each DOI deposit where they want to make references openly available. By setting this element, references for the DOI will be distributed without restriction through all of CrossRefs APIs and bulk metadata dumps. Further details can be found in CrossRef’s schema documentation for the <reference_distribution_opt> element.

    +

    References made in publications arising from agency funding can provide agencies with an overview of what literature is considered important in the fields that they fund. Many publishers deposit references to CrossRef as part of their participation CrossRef’s CitedBy service. However, participation in CitedBy does not automatically make references available via CrossRef’s standard APIs. In order for publishers to distribute references along with standard bibliographic metadata, publishers need to set the <reference_distribution_opt> element to any for each DOI deposit where they want to make references openly available. By setting this element, references for the DOI will be distributed without restriction through all of CrossRefs APIs and bulk metadata dumps. Further details can be found in CrossRef’s schema documentation for the <reference_distribution_opt> element.

    CrossMark

    @@ -446,11 +462,11 @@

    Abstracts

    Many funding agencies are interested in building custom portals that highlight agency-funded research. In order to provide users of these portals with the best experience, agencies will want, where possible, to display abstracts of publications along with their standard bibliographic metadata.

    -

    CrossRef supports the deposit of abstracts conforming to the JATS abstract element. Further details can be found in the CrossRef Schema Documentation of the <abstract> element.

    +

    CrossRef supports the deposit of abstracts conforming to the JATS abstract element. Further details can be found in the CrossRef Schema Documentation of the <abstract> element.

    ORCIDs

    -

    ORCIDs are unique identifiers for researchers. CrossRef supports the deposit of ORCIDs for authors. The presence of ORCIDs in CrossRef metadata will, in turn, allow agencies to tie agency funded research publications directly to researchers. Widespread use of ORCIDs in CrossRef deposits could even let agencies start to develop publication KPIs for researchers that they fund. Further details on CrossRef’s ORCID support can be found in the CrossRef Schema Documentation of the <ORCID> element

    +

    ORCIDs are unique identifiers for researchers. CrossRef supports the deposit of ORCIDs for authors. The presence of ORCIDs in CrossRef metadata will, in turn, allow agencies to tie agency funded research publications directly to researchers. Widespread use of ORCIDs in CrossRef deposits could even let agencies start to develop publication KPIs for researchers that they fund. Further details on CrossRef’s ORCID support can be found in the CrossRef Schema Documentation of the <ORCID> element

    Frequently Asked Questions

    @@ -478,7 +494,7 @@

    XML Deposit Examples

    Full Deposits

    -

    Full deposits use the standard deposit schema.

    +

    Full deposits use the standard deposit schema.

    Background

    @@ -340,7 +341,7 @@

    Resource components and identifiers

    Combining resource components

    -

    Resource components can be combined to narrow down selections.

    +

    The works component can be appended to other resources.

    @@ -357,8 +358,8 @@

    Combining resource components

    - - + + @@ -410,9 +411,14 @@

    Parameters

    /works/{doi}/fundersreturns list of funders associated with the specified CrossRef DOI/works/{doi}returns information about the specified CrossRef DOI
    /funders/{funder_id}/works
    +

    Multiple filters can be specified by separating name:value pairs with a comma:

    + +
    http://api.crossref.org/works?filter=has-orcid:true,from-pub-date:2004-04-04
+
    +

    Example query using URI parameters

    -
    http://api.crossref.org/funders/100000015/works?query=electron+pairs&filter=has-orcid:true&rows=1
+
    http://api.crossref.org/funders/100000015/works?query=global+state&filter=has-orcid:true&rows=1
 
    
 
 
    Example query using JSON in body of GET request
    
@@ -526,12 +532,12 @@ 
    Filter Names
    
 
 	public-references
 	
-	metadata where publishers allow references to be distributed publically.
+	metadata where publishers allow references to be distributed publically. [1]
 
 
 	has-archive
 	
-	metadata which include name of archive partner[1]
+	metadata which include name of archive partner[1]
 
 
 	archive
@@ -578,9 +584,9 @@ 
    Rows
    
 
 
    Offset
    
 
-
    The number of returned items is controlled by the rows parameter, but you can select the Nth set of rows by using the offset parameter. So, for example, to select the second set of 5 results (i.e. results 6 through 10), you would do the following:
    
+
    The number of returned items is controlled by the rows parameter, but you can select the offset into the result list by using the offset parameter. So, for example, to select the second set of 5 results (i.e. results 6 through 10), you would do the following:
    
 
-
    http://api.crossref.org/works?query=allen+renear&rows=5&offset=2
+
    http://api.crossref.org/works?query=allen+renear&rows=5&offset=5
 
    
 
 
    Sample
    
@@ -596,24 +602,26 @@ 
    Example Queries
    
 
 
    All works published by owner prefix 10.1016 in January 2010
    
 
-
    http://api.crossref.org/publishers/10.5555/works?filter=from-pub-date:2010-01,until-pub-date:2010-01
+
    http://api.crossref.org/publishers/10.1016/works?filter=from-pub-date:2010-01,until-pub-date:2010-01
 
    
 
 
    All works funded by funder_id that have a CC-BY license
    
 
-
    http://api.crossref.org/publishers/10.5555/works?filter=license.uri:http://creativecommons.org/licenses/by/3.0/deed.en_US
+
    http://api.crossref.org/publishers/10.5555/works?filter=license.url:http://creativecommons.org/licenses/by/3.0/deed.en_US
 
    
 
-
    All works published by owner prefix 10.5555 in February 2015 that have a CC-BY license
    
+
    All works published by owner prefix 10.5555 from February 2010 to February 2013 that have a CC-BY license
    
 
-
    http://api.crossref.org/publishers/10.5555/works?filter=license.uri:http://creativecommons.org/licenses/by/3.0/deed.en_US,from-pub-date:2015-02,until-pub-date:2015-02
+
    http://api.crossref.org/publishers/10.5555/works?filter=license.url:http://creativecommons.org/licenses/by/3.0/deed.en_US,from-pub-date:2010-02,until-pub-date:2013-02
 
    
 
-
    All works funded by 10.13039/100005235 where license = CC-BY and embargo <= 365 days
    
+
    All works funded by 10.13039/100000015 where license = CC-BY and embargo <= 365 days
    
 
-
    http://api.crossref.org/funders/10.13039/100005235/works?filter=license.uri:http://creativecommons.org/licenses/by/3.0/deed.en_US,license.max-embargo-days:365
+
    http://api.crossref.org/funders/10.13039/100000015/works?filter=license.url:http://creativecommons.org/licenses/by/3.0/deed.en_US,license.delay:365
 
    
 
+
    Note that the filters for license URL and maximum license embargo period (license.url and license.delay) combine to filter each document’s metadata for a license with both of these properties.
    
+
 
    All works funded by X where the archive partner listed = ‘LOCKSS’
    
 
 
    Coming soon.
    
@@ -651,6 +659,8 @@ 
    How to manage API versions
    
 
 
    If you omit a specific version in your ACCEPT header, the system will default to using the latest version of the API. 
    
 
+
    Note that requesting a version of the API via content type is not yet supported.
    
+
 
    Error messages
    
 
 
    There will be no errors, and therefor error messages will be unnecessary. But seriously… coming soon.
    

From bafb523380f21e38d279f7216c8edc1f4347c2ee Mon Sep 17 00:00:00 2001
From: Karl Jonathan Ward 
Date: Fri, 13 Dec 2013 20:30:54 +0000
Subject: [PATCH 005/219] Add docs on /types, type filter and issn filter.

---
 funder_kpi_api.md | 12 +++++++++---
 1 file changed, 9 insertions(+), 3 deletions(-)

diff --git a/funder_kpi_api.md b/funder_kpi_api.md
index 1ad1633..22cf530 100644
--- a/funder_kpi_api.md
+++ b/funder_kpi_api.md
@@ -12,6 +12,7 @@
 - v7: 2013-10-02, fixed typos
 - v8: 2013-10-17, updated warning. Added email address
 - v9: 2013-12-13, update example urls
+- v10: 2013-12-13, /types routes, type filter, issn filter
 
 ## Background
 
@@ -99,9 +100,10 @@ These can be used alone like this
 
 | resource      | description                       |
 |:--------------|:----------------------------------|
-| `/works`      | returns a list of all works (journal articles, conference proceedings, books, components, etc), 20 per page.
+| `/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)
-| `/publishers` |r eturns a list of all publishers.|
+| `/publishers` | returns a list of all publishers|
+| `/types`      | returns a list of valid work types | 
 
 
 ### Resource components and identifiers
@@ -111,7 +113,8 @@ Resource components can be used in conjunction with identifiers to retrieve the
 |:----------------------------|:----------------------------------|
 | `/works/{doi}`              | returns metadata for the specified CrossRef DOI. |
 | `/funders/{funder_id}`      | returns metadata for specified funder **and** its suborganizations |
-| `/publishers/{owner_prefix}` | returns metadata for the specified publisher. |
+| `/publishers/{owner_prefix}` | returns metadata for the specified publisher |
+| `/types/{type_id}` | returns information about a metadata work type |
 
 ### Combining resource components
 
@@ -121,6 +124,7 @@ The works component can be appended to other resources.
 |:----------------------------|:----------------------------------|
 | `/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}/works` | returns list of works of type `type` |
 | `/publishers/{owner_prefix}/works` | returns list of works associated with specified `owner_prefix` |
 
 
@@ -191,6 +195,8 @@ Filters allow you to narrow queries. All filter results are lists.  The followin
 | `archive` | `{string}` | metadata which where value of archive partner is `{string}`[^*] |
 | `has-orcid` | | metadata which includes one or more ORCIDs |
 | `orcid` | `{orcid}` | metadata where `` element's value = `{orcid}` |
+| `issn` | `{issn}` | metadata where record has an ISSN = `{issn}`. Format is `xxxx-xxxx`. |
+| `type` | `{type}` | metadata records whose type = `{type}`. Type must be an ID value from the list of types returned by the `/types` resource |
 
 [^*]: Not implemented yet.
 

From f481d3d2799c91fe1b57b048e15085596f977d99 Mon Sep 17 00:00:00 2001
From: Karl Jonathan Ward 
Date: Sat, 14 Dec 2013 15:20:42 +0000
Subject: [PATCH 006/219] Clarify index timestamp, archive, has-archive.

---
 funder_kpi_api.md | 15 +++++++++++++--
 1 file changed, 13 insertions(+), 2 deletions(-)

diff --git a/funder_kpi_api.md b/funder_kpi_api.md
index 22cf530..ac0141b 100644
--- a/funder_kpi_api.md
+++ b/funder_kpi_api.md
@@ -13,6 +13,7 @@
 - v8: 2013-10-17, updated warning. Added email address
 - v9: 2013-12-13, update example urls
 - v10: 2013-12-13, /types routes, type filter, issn filter
+- v11: 2013-12-14, indexed timestamps, has-archive and archive implemented
 
 ## Background
 
@@ -179,6 +180,8 @@ Filters allow you to narrow queries. All filter results are lists.  The followin
 |:-----------|:----------------|:-----------|
 | `funder` | `{funder_id}` | metadata which include the `{funder_id}` in FundRef data |
 | `publisher` | `{owner_prefix}` | metadata belongs to published identified by `{owner_prefix}` (e.g. `10.1016` ) |
+| `from-index-date` | `{date}` | metadata indexed since (inclusive) `{date}` |
+| `until-index-date` | `{date}` | metadata indexed before (inclusive) `{date}` |
 | `from-update-date` | `{date}` | metadata updated since (inclusive) `{date}` |
 | `until-update-date` | `{date}` | metadata updated before (inclusive) `{date}` |
 | `from-pub-date` | `{date}` | metadata where published date is since (inclusive) `{date}` |
@@ -191,8 +194,8 @@ Filters allow you to narrow queries. All filter results are lists.  The followin
 | `full-text.version` | `{string}`  | metadata where `` element's `content_version` attribute is `{string}`. |
 | `full-text.type` | `{mime_type}`  | metadata where `` element's `content_type` attribute is `{mime_type}` (e.g. `application/pdf`). |
 | `public-references` | | metadata where publishers allow references to be distributed publically. [^*] |
-| `has-archive` | | metadata which include name of archive partner[^*] |
-| `archive` | `{string}` | metadata which where value of archive partner is `{string}`[^*] |
+| `has-archive` | | metadata which include name of archive partner |
+| `archive` | `{string}` | metadata which where value of archive partner is `{string}` |
 | `has-orcid` | | metadata which includes one or more ORCIDs |
 | `orcid` | `{orcid}` | metadata where `` element's value = `{orcid}` |
 | `issn` | `{issn}` | metadata where record has an ISSN = `{issn}`. Format is `xxxx-xxxx`. |
@@ -208,6 +211,14 @@ The prefix of a CrossRef DOI does **NOT** indicate who currently owns the DOI. I
 
 Note that dates in filters should always be of the form `YYYY-MM-DD`. Also not 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
+
+When using time filters to retrieve periodic, incremental metadata updates,
+the `from-index-date` filter should be used over `from-update-date`,
+`from-deposit-date`, `from-first-deposit-date` and `from-pub-date`. The
+timestamp that `from-index-date` filters on is guaranteed to be updated
+every time there is a change to metadata requiring a reindex.
+
 ## Result controls
 
 You can control the delivery and selection  results using the `rows`, `offset` and `sample` parameters. 

From f4eb657bfcc4db2163078db98359340393721e12 Mon Sep 17 00:00:00 2001
From: Karl Jonathan Ward 
Date: Sat, 14 Dec 2013 15:26:31 +0000
Subject: [PATCH 007/219] Add first-deposit-date, deposit-date filters.

---
 funder_kpi_api.md | 8 ++++++--
 1 file changed, 6 insertions(+), 2 deletions(-)

diff --git a/funder_kpi_api.md b/funder_kpi_api.md
index ac0141b..0e89afa 100644
--- a/funder_kpi_api.md
+++ b/funder_kpi_api.md
@@ -182,8 +182,12 @@ Filters allow you to narrow queries. All filter results are lists.  The followin
 | `publisher` | `{owner_prefix}` | metadata belongs to published identified by `{owner_prefix}` (e.g. `10.1016` ) |
 | `from-index-date` | `{date}` | metadata indexed since (inclusive) `{date}` |
 | `until-index-date` | `{date}` | metadata indexed before (inclusive) `{date}` |
-| `from-update-date` | `{date}` | metadata updated since (inclusive) `{date}` |
-| `until-update-date` | `{date}` | metadata updated before (inclusive) `{date}` |
+| `from-deposit-date` | `{date}` | metadata last (re)deposited since (inclusive) `{date}` |
+| `until-deposit-date` | `{date}` | metadata last (re)deposited before (inclusive) `{date}` |
+| `from-update-date` | `{date}` | Metadata updated since (inclusive) `{date}`. Currently the same as `from-deposit-date`. |
+| `until-update-date` | `{date}` | Metadata updated before (inclusive) `{date}`. Currently the same as `until-deposit-date`. |
+| `from-first-deposit-date` | `{date}` | metadata first deposited since (inclusive) `{date}` [^*] |
+| `until-first-deposit-date` | `{date}` | metadata first deposited before (inclusive) `{date}` [^*] |
 | `from-pub-date` | `{date}` | metadata where published date is since (inclusive) `{date}` |
 | `until-pub-date` | `{date}` | metadata where published date is before (inclusive)  `{date}` |
 | `has-license` | | metadata that includes any `` elements. |

From 14299a7d946e12eb676546f837e93da12b733d26 Mon Sep 17 00:00:00 2001
From: Karl Jonathan Ward 
Date: Mon, 6 Jan 2014 10:23:56 +0000
Subject: [PATCH 008/219] Mention directory filter.

---
 funder_kpi_api.md | 1 +
 1 file changed, 1 insertion(+)

diff --git a/funder_kpi_api.md b/funder_kpi_api.md
index 0e89afa..20305bf 100644
--- a/funder_kpi_api.md
+++ b/funder_kpi_api.md
@@ -204,6 +204,7 @@ Filters allow you to narrow queries. All filter results are lists.  The followin
 | `orcid` | `{orcid}` | metadata where `` element's value = `{orcid}` |
 | `issn` | `{issn}` | metadata where record has an ISSN = `{issn}`. Format is `xxxx-xxxx`. |
 | `type` | `{type}` | metadata records whose type = `{type}`. Type must be an ID value from the list of types returned by the `/types` resource |
+| `directory` | `{directory}` | metadata records whose article or serial are mentioned in the given `{directory}`. Currently the only supported value is `doaj`. |
 
 [^*]: Not implemented yet.
 

From eebb0ed09dd101c10f85632e7cea24f78d17fa7e Mon Sep 17 00:00:00 2001
From: Karl Jonathan Ward 
Date: Mon, 6 Jan 2014 10:24:27 +0000
Subject: [PATCH 009/219] Version bump.

---
 funder_kpi_api.md | 1 +
 1 file changed, 1 insertion(+)

diff --git a/funder_kpi_api.md b/funder_kpi_api.md
index 20305bf..e9b9179 100644
--- a/funder_kpi_api.md
+++ b/funder_kpi_api.md
@@ -14,6 +14,7 @@
 - v9: 2013-12-13, update example urls
 - v10: 2013-12-13, /types routes, type filter, issn filter
 - v11: 2013-12-14, indexed timestamps, has-archive and archive implemented
+- v12: 2014-01-06, directory filter
 
 ## Background
 

From cae97d183008f6cf4f1cf4e3938f84c61428d41a Mon Sep 17 00:00:00 2001
From: Geoffrey Bilder 
Date: Wed, 8 Jan 2014 13:26:13 +0100
Subject: [PATCH 010/219] added text on content syndication

---
 ...t_syndication_through_crossref_metadata.md |  98 +++++++++++
 scratch.md                                    | 153 ++++++++++++++++++
 2 files changed, 251 insertions(+)
 create mode 100644 content_syndication_through_crossref_metadata.md
 create mode 100644 scratch.md

diff --git a/content_syndication_through_crossref_metadata.md b/content_syndication_through_crossref_metadata.md
new file mode 100644
index 0000000..73ef587
--- /dev/null
+++ b/content_syndication_through_crossref_metadata.md
@@ -0,0 +1,98 @@
+
+
+# Content Syndication Through CrossRef Metadata
+
+## The Problem
+
+There is concern that the CrossRef schema does not give enough information to users about which resources are appropriate for different user classes and/or applications. For example, a publisher might want to be able to provide different lists of resources for the following use cases:
+
+- A human subscriber accessing the content to read 
+- A human non-subscriber accessing the content to read 
+- A human from an entitled funding agency accessing the content to read
+
+- A bot run by a subscriber accessing the content to TDM
+- A bot run by a non-subscriber accessing the content to TDM
+- A bot run by an entitled funding agency accessing the content to TDM
+
+- A bot run by a subscriber accessing the content to syndicate
+- A bot run by a non-subscriber accessing the content to syndicate
+- A bot run by an entitled funding agency accessing the content to syndicate
+
+In the above cases, the content in question might or be either "restricted" (e.g.  requiring a subscription to access) or "unrestricted" (open access, free). Furthermore, any restrictions may be time-boxed via embargoes. This effectively means that their are sub-cases where the desired behavior might change depending on when the user (bot or human) tries to access the content.
+
+ So for the above use cases the publisher might want the user to select a resource that points to either:
+
+- A human readable landing page on the publisher's main website.
+- A human readable representation of the VOR (e.g. PDF, HTML, etc.) on the publisher's main website.
+- A human readable representation of the AAM (e.g. PDF, HTML, etc.) on the publisher's main website.
+
+- A machine readable representation of the VOR (e.g. XML, Plain Text) on the publisher's TDM server
+- A machine readable representation of the AAM (e.g. XML, Plain Text) on the publisher's TDM server
+
+- A human readable representation of the VOR (e.g. PDF, HTML, etc.) on the publisher's syndication server.
+- A human readable representation of the AAM (e.g. PDF, HTML, etc.) on the publisher's syndication server.
+
+
+Selecting the appropriate resource would seem to hinge on three criteria:
+
+- Is the agent a human or a bot?
+- Is the content under restricted access? For example, is a subscription needed?, is the content currently under embargo?
+- is the agent entitled at this particular time?
+- What is the desired application? Viewing, indexing, syndication, tdm?
+
+
+We have used the term "BAV" to describe the "Best Available Version."- where "version" refers to the JATS version of a document (i.e. AAM, VOR). The idea is that some versions of the document (e.g. VOR) may be under restricted access (e.g. under embargo, require a subscription) and are thus "unavailable" to certain classes of user, while other versions of the document (e.g. AAM) are not under restrictions and are thus "available" to the respective class of user.
+
+But the above use-cases introduce another facet that may need to be considered when selecting a resource- the "Appropriate Application Resource" (AAR). That is, the use-cases above imply that publishers might want to direct users at resources pointing to systems that are optimized to support a particular application. For example, a publisher might have a server that is reserved for search engines, or for syndication partners, etc. 
+
+## Providing Hints For Selecting a BAV
+
+The normative HTTP mechanism to handle these requirements technically, would be to use content negotiation. That is, an agent could request a resource using a GET and be shown the options for different available versions of the resource in the response headers. The user agent would then select the BAV/AAR from the options presented in the publisher's response. In other words, ideally the system would work the same way that content negotiation works for languages or for browser feature sets.
+
+However, CrossRef recognizes that, in the short/medium term, it would be impractical to expect all of our members to integrate such content negotiation in their publishing sites. Thus we have added the ability for publisher to record attributes of the resource that one would normally use content negotiation for in selecting a BAV. Specifically, we have added the following two attributes to the resource element:
+
+- mime_type
+- content_version
+
+ This allows the publisher to record resources for all the combinations of representation (PDF,HTML, Etc.) and version (VOR, AAM) that the publisher supports. In turn, the user can use these attributes to determine a-priori (i.e. without having to do an HTTP query for content negotiation)  which versions of the content **exist**. However, it does give the user any information to a-priori determine which versions of the content are likely to be **available**. In other words, just because the HTTP URI of a particular representation of a particular version of the content is listed, that doesn't mean that the user is guaranteed to be able to access the resource. The resource might require a subscription, it might be under embargo, etc.
+
+ The addition of the `AccessIndicators` section to the CrossRef schema provides a mechanism that allows publishers to provide resource-specific information about the *purported accessibility* of the content pointed to by the resource using extended versions of the NISO-recommended `` and `` elements. The `//AccessIndicators/license_ref` element has been extended with an "applies_to" attribute which can be used to map specific licenses (identified by HTTP URIs) to specific resources based on their content_version. So, for example, this enables a publisher to link one license to the resource that points to the VOR of the content and a different license to the resource that points to the AAM of the content. Similarly, the publisher will be able to map the `//AccessIndicators/free-to-read` element to specific resources identified by the content_version attribute in order to indicate that the content pointed to by a resource is available to "view" without any payment or registration preconditions.
+
+ The `` element can also include a `start_date` attribute, which can be used to indicate when a license takes effect. This, in turn, can be used to record simple embargo information and to map that information to a specific version of the `` identified by the `content_type` attribute.
+
+ For example, the following records that the VOR of the content is under a proprietary license from its date of publication on February 3, 2014 and that it is under a CC-BY license a year later on February 3, 2015 **and* that the AAM of the content is available from the date of publication under a CC-BY license:
+
+
+    http://www.psychoceramics.org/fulltext/vor/10.5555/12345678
+    http://www.psychoceramics.org/fulltext/am/10.5555/12345678
+    
+    http://www.psychoceramics.org/license_v1.html
+    http://creativecommons.org/licenses/by/3.0/deed.en_US
+    http://creativecommons.org/licenses/by/3.0/deed.en_US
+
+
+The addition of the `AccessIndicators` allows the publisher to indicate not only what versions of the resource **exist** , but also for the publisher to provide a mechanism for the user to determine a-priori (without doing an HTTP get for content negotiation) which versions of the resource are likely to be **available**. In short, the combination of `//AccessIndicator` elements and `//collection/resource` elements allows the user to determine the **BAV**. 
+
+## Providing Hints For Selecting a AAR
+
+But this still leaves us with the question of how to provide the publisher to provide the user with hints as to which version of a resource is appropriate for a particular application. So-far we have identified the following applications:
+
+1) Viewing (e.g. on the publisher's web site, via landing page, etc.)
+2) Indexing (e.g. for search engines, etc.)
+
+
+ Currently we already have three existing mechanisms for labeling different 'applications' of the resource. 
+
+ The first mechanism is implicit. That is  `/doi_data/resource` attributes have normatively recorded a link to the publisher landing page, from which the human reader can get a "viewable" version of the resource. 
+
+ The second two are encoded in the the `property` attribute of the `` container element. We currently support several values for this property, including `crawler-based` which was intended to be used to identify resources for search engines (i.e. indexing) and `text-mining` which has been introduced for resources designed for TDM bots. What seems to be missing is a value for "syndication." If we were to add a `syndication` attribute value then publishers would be able to record `/collection/resource` elements that meet all the use-cases identified above.  
+
+ ## Limitations of proposed system
+
+ The hints provided in CrossRef metadata are just that, hints. There is nothing that CrossRef can do to force users to select an particular resource appropriate to their application. Thus, it is still going to be the responsibility of the publisher to check requests and to route them appropriately. 
+
+
+
+
+
+
diff --git a/scratch.md b/scratch.md
new file mode 100644
index 0000000..8b0b227
--- /dev/null
+++ b/scratch.md
@@ -0,0 +1,153 @@
+# Content "Syndication" through CrossRef Metadata
+## Current situation
+
+### Normative behavior for resolving CrossRef DOIs
+
+When CrossRef DOIs are resolved via a browser, they  redirect to the HTTP URI recorded by the publisher in the element `doi_data/resource`. The URI recorded in `doi_data/resource` typically points to a "landing page. This landing page, in turn, typically presents:
+
+1. Human readable bibliographic metadata 
+2. Link(s) that enable one to acquire one or more human-readable full text representations of the resource (e.g. PDF, HTML, ePub) and/or one or more versions of the resource (e.g. AAM, VOR, etc.) 
+
+Because the publisher controls the landing page, they can show/hide appropriate acquisition links according to their access control requirements and the status of the user viewing the landing page.
+
+Note that not all CrossRef DOIs behave this way, but the vast majority do. The above is normative behavior for CrossRef DOIs.
+
+Some aspects of this normative behavior are worth highlighting:
+
+1) The default behavior is designed for humans
+2) The publisher system needs to make decisions about what the user is allowed to access from the landing page
+3) This mechanism is currently used (abused?) by numerous text mining tools, etc. via screen scraping techniques as it is often the most convenient (only) way to get full text representations of the content identified by the DOI.
+
+### Extended CrossRef DOI resolution mechanisms  
+
+#### "As-Crawled URLs"
+
+In order to better support the use of CrossRef DOIs by search engines, the CrossRef metadata schema was extended. Specifically, CrossRef members wanted to be able to:
+
+1. Direct search engines to platforms that were designed to handle the additional load imposed by search engines
+2. Provide search engines with representations that were optimized for indexing (and, occasionally, which where degraded for "reading"). 
+
+ CrossRef introduced the `` element. The collection element is a container element that can include any number of "alternative" `` elements. Each `/collection/resource` element, in turn, includes a "crawler" attribute so that specific search engine crawlers could be directed at specific `resource` URIs.
+
+In order to use this mechanism, search engines needed to either:
+
+a) Make use of CrossRef's proprietary API for accessing the metadata for a DOI and looking up the alternative resources.
+b) Subscribe to dumps of CrossRef's metadata.
+
+As such, no major search engine uses this mechanism for indexing CrossRef member web sites. Similarly, very few CrossRef members make use of the `collection/resource` element to support search engines. Of those that do record "as-crawled" URLs, none record separate URIs for different crawlers.
+
+A typical section for as-crawled resources looks like this:
+
+    
+              
+                http://downloads.hindawi.com/journals/ijps/2013/435073.pdf
+              
+              
+                http://downloads.hindawi.com/journals/ijps/2013/435073.pdf
+              
+              
+                http://downloads.hindawi.com/journals/ijps/2013/435073.pdf
+              
+              
+                http://downloads.hindawi.com/journals/ijps/2013/435073.pdf
+              
+              
+                http://downloads.hindawi.com/journals/ijps/2013/435073.pdf
+              
+     
+
+
+In 2007, the "crawler" attribute was extended to support the iParadigms crawler for CrossCheck, but again, very few publishers make use of it.
+
+#### Content Negotiation
+
+In 2011 CrossRef introduced content negotiation for CrossRef DOIs. This mechanism provides a standard way for tools to request machine-readable representations of a CrossRef DOI's metadata. It also encourages both publishers and users of CrossRef metadata to follow standard linked-data mechanisms for recording alternative and related resource representations in their metadata using HTTP URIs.
+
+#### Text and Data Mining (aka Prospect)  
+
+In order to support text and data mining applications, CrossRef is encouraging publishers to has proposed using content negotiation and the current CrossRef metadata schema to support recording links to resource representations designed for text and data mining. 
+
+
+
+But it is entirely up to the user as to how they make use of this information.
+
+This is a critical point, because even though we are providing 'hints' to the user on which version of the resource is likely to be available to them, there is nothing the CrossRef can do to force the user to make use of these hints. There is nothing we can do to stop an un-subscribed user from trying to retrieve the VOR of content that is restricted to subscribers. It is still entirely up to the publisher to appropriately **enforce** the guidelines that they have documented in the CrossRef metadata. 
+
+
+
+"Appropriate Application Resource"
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+crawler="subsciber"
+crawler="public"
+crawler="syndicator"
+
+
+(TBD- note that multiple resolution slightly more complicated)
+
+This effectively means that doi_data/resource 
+
+
+ means mediated access for humans
+
+
+
+In theory, this resource can point to "the thing itself" or to "something abou"
+
+we then have following sections:
+
+"as-crawled" for search engines
+
+"text-mining" misnomer- but set that aside for a bit
+
+What are things we want to distnguish:
+
+Batch v Query
+
+Human v Bot
+
+*minimally* they want to text mine what they can see- e.g. the PDF. So conflating this made sense- until Elsevier came around.
+
+OPDS has what they call "aquisition links" where rel attribute is set to a URI indicating what is being pointed to. They have the following types:
+
+http://opds-spec.org/acquisition/open-access for Open Access publications
+http://opds-spec.org/acquisition/buy for publications that you can buy
+http://opds-spec.org/acquisition/borrow for publications that you can borrow
+http://opds-spec.org/acquisition/subscribe for publications that you can subscribe to
+http://opds-spec.org/acquisition/sample to sample a publication
+http://opds-spec.org/acquisition when none of the other values are appropriate or you don't have additional information
+
+These are problematic because they conflate various things. For example, something can CC-BY-SA , but paid for. For example:
+
+http://www.amazon.co.uk/Little-Brother-Cory-Doctorow-ebook/dp/B008TGKXWW/ref=sr_1_1?s=books&ie=UTF8&qid=1389085868&sr=1-1&keywords=Little+Brother
+
+And at the same time CC-BY-SA and for free:
+
+http://craphound.com/littlebrother/download/
+
+
+
+              
+                http://annalsofpsychoceramics.labs.crossref.org/fulltext/10.5555/515151.pdf
+              
+              
+                http://annalsofpsychoceramics.labs.crossref.org/fulltext/10.5555/515151.xml
+              
+            
+
+

From 2d0be8a80303097fd7f5ebae3ddf9d3440fe747a Mon Sep 17 00:00:00 2001
From: Geoffrey Bilder 
Date: Wed, 8 Jan 2014 13:27:56 +0100
Subject: [PATCH 011/219] added HTML on content syndication

---
 ...syndication_through_crossref_metadata.html | 271 ++++++++++++++++++
 ...t_syndication_through_crossref_metadata.md |   4 +
 2 files changed, 275 insertions(+)
 create mode 100644 content_syndication_through_crossref_metadata.html

diff --git a/content_syndication_through_crossref_metadata.html b/content_syndication_through_crossref_metadata.html
new file mode 100644
index 0000000..d714eeb
--- /dev/null
+++ b/content_syndication_through_crossref_metadata.html
@@ -0,0 +1,271 @@
+  
+
+
+  
+  
+  content_syndication_through_crossref_metadata
+  
+  
+
+
+
+  
    
+      
    Content Syndication Through CrossRef Metadata
    
+
+
    Version History
    
+
+
      
+
    • V1 2014–01–08, Initial draft
      • 
+
    
+
+
    The Problem
    
+
+
    There is concern that the CrossRef schema does not give enough information to users about which resources are appropriate for different user classes and/or applications. For example, a publisher might want to be able to provide different lists of resources for the following use cases:
    
+
+
      
+
    • A human subscriber accessing the content to read 
      • 
+
    • A human non-subscriber accessing the content to read 
      • 
+
    • A human from an entitled funding agency accessing the content to read
      • 
+
    • A bot run by a subscriber accessing the content to TDM
      • 
+
    • A bot run by a non-subscriber accessing the content to TDM
      • 
+
    • A bot run by an entitled funding agency accessing the content to TDM
      • 
+
    • A bot run by a subscriber accessing the content to syndicate
      • 
+
    • A bot run by a non-subscriber accessing the content to syndicate
      • 
+
    • A bot run by an entitled funding agency accessing the content to syndicate
      • 
+
    
+
+
    In the above cases, the content in question might or be either “restricted” (e.g. requiring a subscription to access) or “unrestricted” (open access, free). Furthermore, any restrictions may be time-boxed via embargoes. This effectively means that their are sub-cases where the desired behavior might change depending on when the user (bot or human) tries to access the content.
    
+
+
    So for the above use cases the publisher might want the user to select a resource that points to either:
    
+
+
      
+
    • A human readable landing page on the publisher’s main website.
      • 
+
    • A human readable representation of the VOR (e.g. PDF, HTML, etc.) on the publisher’s main website.
      • 
+
    • A human readable representation of the AAM (e.g. PDF, HTML, etc.) on the publisher’s main website.
      • 
+
    • A machine readable representation of the VOR (e.g. XML, Plain Text) on the publisher’s TDM server
      • 
+
    • A machine readable representation of the AAM (e.g. XML, Plain Text) on the publisher’s TDM server
      • 
+
    • A human readable representation of the VOR (e.g. PDF, HTML, etc.) on the publisher’s syndication server.
      • 
+
    • A human readable representation of the AAM (e.g. PDF, HTML, etc.) on the publisher’s syndication server.
      • 
+
    
+
+
    Selecting the appropriate resource would seem to hinge on three criteria:
    
+
+
      
+
    • Is the agent a human or a bot?
      • 
+
    • Is the content under restricted access? For example, is a subscription needed?, is the content currently under embargo?
      • 
+
    • is the agent entitled at this particular time?
      • 
+
    • What is the desired application? Viewing, indexing, syndication, tdm?
      • 
+
    
+
+
    We have used the term “BAV” to describe the “Best Available Version.”- where “version” refers to the JATS version of a document (i.e. AAM, VOR). The idea is that some versions of the document (e.g. VOR) may be under restricted access (e.g. under embargo, require a subscription) and are thus “unavailable” to certain classes of user, while other versions of the document (e.g. AAM) are not under restrictions and are thus “available” to the respective class of user.
    
+
+
    But the above use-cases introduce another facet that may need to be considered when selecting a resource- the “Appropriate Application Resource” (AAR). That is, the use-cases above imply that publishers might want to direct users at resources pointing to systems that are optimized to support a particular application. For example, a publisher might have a server that is reserved for search engines, or for syndication partners, etc. 
    
+
+
    Providing Hints For Selecting a BAV
    
+
+
    The normative HTTP mechanism to handle these requirements technically, would be to use content negotiation. That is, an agent could request a resource using a GET and be shown the options for different available versions of the resource in the response headers. The user agent would then select the BAV/AAR from the options presented in the publisher’s response. In other words, ideally the system would work the same way that content negotiation works for languages or for browser feature sets.
    
+
+
    However, CrossRef recognizes that, in the short/medium term, it would be impractical to expect all of our members to integrate such content negotiation in their publishing sites. Thus we have added the ability for publisher to record attributes of the resource that one would normally use content negotiation for in selecting a BAV. Specifically, we have added the following two attributes to the resource element:
    
+
+
      
+
    • mime_type
      • 
+
    • content_version
      • 
+
    
+
+
    This allows the publisher to record resources for all the combinations of representation (PDF,HTML, Etc.) and version (VOR, AAM) that the publisher supports. In turn, the user can use these attributes to determine a-priori (i.e. without having to do an HTTP query for content negotiation) which versions of the content exist. However, it does give the user any information to a-priori determine which versions of the content are likely to be available. In other words, just because the HTTP URI of a particular representation of a particular version of the content is listed, that doesn’t mean that the user is guaranteed to be able to access the resource. The resource might require a subscription, it might be under embargo, etc.
    
+
+
    The addition of the AccessIndicators section to the CrossRef schema provides a mechanism that allows publishers to provide resource-specific information about the purported accessibility of the content pointed to by the resource using extended versions of the NISO-recommended <license_reference> and <free-to-read> elements. The //AccessIndicators/license_ref element has been extended with an “applies_to” attribute which can be used to map specific licenses (identified by HTTP URIs) to specific resources based on their content_version. So, for example, this enables a publisher to link one license to the resource that points to the VOR of the content and a different license to the resource that points to the AAM of the content. Similarly, the publisher will be able to map the //AccessIndicators/free-to-read element to specific resources identified by the content_version attribute in order to indicate that the content pointed to by a resource is available to “view” without any payment or registration preconditions.
    
+
+
    The <license_ref> element can also include a start_date attribute, which can be used to indicate when a license takes effect. This, in turn, can be used to record simple embargo information and to map that information to a specific version of the <resource> identified by the content_type attribute.
    
+
+
    For example, the following records that the VOR of the content is under a proprietary license from its date of publication on February 3, 2014 and that it is under a CC-BY license a year later on February 3, 2015 *and that the AAM of the content is available from the date of publication under a CC-BY license:
    
+
+
    <resource content_version="vor">http://www.psychoceramics.org/fulltext/vor/10.5555/12345678</resource>
+<resource content_version="am">http://www.psychoceramics.org/fulltext/am/10.5555/12345678</resource>
+<!-- … -->
+<license_ref applies_to="VOR" start_date="2014-02-03">http://www.psychoceramics.org/license_v1.html</license_ref>
+<license_ref applies_to="VOR" start_date="2015-02-03">http://creativecommons.org/licenses/by/3.0/deed.en_US</license_ref>
+<license_ref applies_to="AAM" start_date="2014-02-03">http://creativecommons.org/licenses/by/3.0/deed.en_US</license_ref>
+
    
+
+
    The addition of the AccessIndicators allows the publisher to indicate not only what versions of the resource exist , but also for the publisher to provide a mechanism for the user to determine a-priori (without doing an HTTP get for content negotiation) which versions of the resource are likely to be available. In short, the combination of //AccessIndicator elements and //collection/resource elements allows the user to determine the BAV. 
    
+
+
    Providing Hints For Selecting a AAR
    
+
+
    But this still leaves us with the question of how to provide the publisher to provide the user with hints as to which version of a resource is appropriate for a particular application. So-far we have identified the following applications:
    
+
+
    1) Viewing (e.g. on the publisher’s web site, via landing page, etc.)
+2) Indexing (e.g. for search engines, etc.)
    
+
+
    Currently we already have three existing mechanisms for labeling different ‘applications’ of the resource. 
    
+
+
    The first mechanism is implicit. That is /doi_data/resource attributes have normatively recorded a link to the publisher landing page, from which the human reader can get a “viewable” version of the resource. 
    
+
+
    The second two are encoded in the the property attribute of the <collection> container element. We currently support several values for this property, including crawler-based which was intended to be used to identify resources for search engines (i.e. indexing) and text-mining which has been introduced for resources designed for TDM bots. What seems to be missing is a value for “syndication.” If we were to add a syndication attribute value then publishers would be able to record /collection/resource elements that meet all the use-cases identified above. 
    
+
+
    ## Limitations of proposed system
    
+
+
    The hints provided in CrossRef metadata are just that, hints. There is nothing that CrossRef can do to force users to select an particular resource appropriate to their application. Thus, it is still going to be the responsibility of the publisher to check requests and to route them appropriately. 
    
+
+
+
+
+    
    
+
+
\ No newline at end of file
diff --git a/content_syndication_through_crossref_metadata.md b/content_syndication_through_crossref_metadata.md
index 73ef587..84147a7 100644
--- a/content_syndication_through_crossref_metadata.md
+++ b/content_syndication_through_crossref_metadata.md
@@ -2,6 +2,10 @@
 
 # Content Syndication Through CrossRef Metadata
 
+## Version History
+
+- V1 2014-01-08, Initial draft
+
 ## The Problem
 
 There is concern that the CrossRef schema does not give enough information to users about which resources are appropriate for different user classes and/or applications. For example, a publisher might want to be able to provide different lists of resources for the following use cases:

From aeee81fd98945e6a3733d9e30847215c141ac08d Mon Sep 17 00:00:00 2001
From: Karl Jonathan Ward 
Date: Mon, 13 Jan 2014 14:39:09 +0000
Subject: [PATCH 012/219] First draft of archive query API spec.

---
 archive_query_api.md | 149 +++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 149 insertions(+)
 create mode 100644 archive_query_api.md

diff --git a/archive_query_api.md b/archive_query_api.md
new file mode 100644
index 0000000..bb72ba9
--- /dev/null
+++ b/archive_query_api.md
@@ -0,0 +1,149 @@
+Archive Arrangement Query API
+=============================
+
+# Change History
+
+| Date | Changes |
+|------|---------|
+| 2014-01-13 | Initial version |
+
+# Background
+
+CrossRef metadata can record the archive arrangement for a piece of content. For example,
+a publisher may deposit copies of their published content with an archive organisation
+such as CLOCKSS or LOCKSS and record this fact in metadata deposited to CrossRef. Each
+DOI record can maintain archive arrangement information separately:
+
+    
+    
+        ...
+		 
+        
+	        
+		    
+        
+    
+        ...
+    
+    
+
+While the archive arrangement information in CrossRef metadata records a publisher's
+intent to archive a certain piece of content with a particular organisation, it does
+not confirm the existence of an archive copy. A third party wishing to validate the
+publisher's claim of an archive arrangement must query the archive organisation
+for the archive state of a piece of content.
+
+To faciliate archive arrangement verification, a common query API is proposed that
+allows any third party to look up the archive state of a piece of content identified
+by a DOI.
+
+# DOI Query Path
+
+A query API implementor must provide a publicly-accessible DOI query path. The path must
+either accept a DOI as a query parameter named `doi`:
+
+    http://anarchive.org/status?doi={DOI}
+
+or, alternatively, accept a DOI as part of a HTTP path:
+
+    http://anarchive.org/status/{DOI}
+
+## DOI Syntax
+
+The implementor must handle the issues of embedding DOIs within HTTP paths and query strings.
+Refer to the `Numbering` section of the [DOI Handbook](http://www.doi.org/doi_handbook/2_Numbering.html) for a detailed discussion of the syntax of DOIs. However, the important points are:
+
+- DOIs are case insensitive
+- DOIs can contain characters that are normally reserved characters within the HTTP specification
+
+# JSON Response
+
+The response to requests to the DOI query path should always be in the JSON representation
+mentioned below, regardless of the representation requested by the client. Therefore, the
+client's `Accept` header is always ignored, and the only valid `Content-Type` response header
+is `application/json`, or `application/json; charset=UTF-8`, where the charset value may
+be set to any value appropriate for the response body.
+
+A valid JSON response contains a `message-type` and the `message` itself. Two message types
+are specified:
+
+| Type | Meaining |
+|------|----------|
+| archive | Response to a successful DOI query |
+| error | Response to a failed DOI query |
+
+## Archive
+
+An archive message represents the archive state of the content associated with a given
+DOI. It can comprise of these properties:
+
+| Name | Optional? | Value | Description |
+|------|-----------|-------|-------------|
+| doi | No | A DOI without any adornment (`doi:` etc.) e.g. `10.5555/12345678` | The query DOI an archive response refers to. |
+| archived_at | Yes | A valid [ISO 8601](http://en.wikipedia.org/wiki/ISO_8601) date or date and time string | Date or date and time at which a copy of content was received for archiving. Omission of this element indicates that no archive copy has been received for the query DOI. |
+| archived_state | Yes | `dark` or `light` | Whether an archive copy is light or dark. Only valid if `archived_at` is present. |
+| archived_location | Yes | Any URL | Publicly accessible download location for the archive copy. Onlu valid if `archived_at` is present. |
+
+## Error
+
+An error response contains a message with two required properties: `error_message` and `error_code`. `error_message` may contain a human readable explanation for any error (or, if that is not available, any additional information about the error). `error_code` must be set to the same value as the HTTP response code, which itself must be an HTTP error code in the 4xx or 5xx range.
+
+## Response Headers
+
+A HTTP response to the DOI query path may contain any headers, but must include a `Content-Type`
+header, and in the case of a redirect must include a `Location` header.
+
+## Response Examples
+
+Response for a DOI whose content has been received by the archive, but is currently dark:
+
+    {
+	  "message-type": "archive",
+	  "message": {
+	    "doi": "10.5555/12345678"
+	    "archived_at": "2014-01-13T12:24Z",
+		"archived_state": "dark"
+      }
+	}
+
+Response for a DOI whose content has not been received by the archive:
+
+    {
+      "message-type": "archive",
+	  "message": {
+	    "doi": "10.5555/12345678"
+	  }
+	}
+
+Response for a DOI whose content has been received by the archive and for which there
+has been a trigger event, making the content become light:
+
+    {
+	  "message-type": "archive",
+	  "message": {
+        "doi": "10.5555/12345678",
+		"archived_at": "2014-01-13T12:24Z",
+		"archived_state": "light",
+		"archived_location": "http://anarchive.org/archive/10.5555/12345678"
+	  }
+	}
+
+An error response:
+
+    {
+	  "message-type": "error",
+	  "message": {
+	    "error_message": "Upstream service is currently unavailable.",
+		"error_code": 506
+	  }
+	}
+
+# Response Codes
+
+Responses to the DOI query path should incorporate all appropriate HTTP error codes.
+Clients should expect to receive any valid HTTP response code, including redirects
+and errors. In the case of redirects, clients should follow the `Location` header.
+In the case of error codes, clients should implement a reasonable decaying retry
+mechanism.
+
+Clients are not expected to deal with any form of rate-limiting HTTP headers.

From 5919a36488aaadacdb87ba14f6b294151a43c3e4 Mon Sep 17 00:00:00 2001
From: Karl Jonathan Ward 
Date: Mon, 13 Jan 2014 14:41:30 +0000
Subject: [PATCH 013/219] Bump headers.

---
 archive_query_api.md | 20 ++++++++++----------
 1 file changed, 10 insertions(+), 10 deletions(-)

diff --git a/archive_query_api.md b/archive_query_api.md
index bb72ba9..7c1338d 100644
--- a/archive_query_api.md
+++ b/archive_query_api.md
@@ -1,13 +1,13 @@
 Archive Arrangement Query API
 =============================
 
-# Change History
+## Change History
 
 | Date | Changes |
 |------|---------|
 | 2014-01-13 | Initial version |
 
-# Background
+## Background
 
 CrossRef metadata can record the archive arrangement for a piece of content. For example,
 a publisher may deposit copies of their published content with an archive organisation
@@ -37,7 +37,7 @@ To faciliate archive arrangement verification, a common query API is proposed th
 allows any third party to look up the archive state of a piece of content identified
 by a DOI.
 
-# DOI Query Path
+## DOI Query Path
 
 A query API implementor must provide a publicly-accessible DOI query path. The path must
 either accept a DOI as a query parameter named `doi`:
@@ -48,7 +48,7 @@ or, alternatively, accept a DOI as part of a HTTP path:
 
     http://anarchive.org/status/{DOI}
 
-## DOI Syntax
+### DOI Syntax
 
 The implementor must handle the issues of embedding DOIs within HTTP paths and query strings.
 Refer to the `Numbering` section of the [DOI Handbook](http://www.doi.org/doi_handbook/2_Numbering.html) for a detailed discussion of the syntax of DOIs. However, the important points are:
@@ -56,7 +56,7 @@ Refer to the `Numbering` section of the [DOI Handbook](http://www.doi.org/doi_ha
 - DOIs are case insensitive
 - DOIs can contain characters that are normally reserved characters within the HTTP specification
 
-# JSON Response
+## JSON Response
 
 The response to requests to the DOI query path should always be in the JSON representation
 mentioned below, regardless of the representation requested by the client. Therefore, the
@@ -72,7 +72,7 @@ are specified:
 | archive | Response to a successful DOI query |
 | error | Response to a failed DOI query |
 
-## Archive
+### Archive
 
 An archive message represents the archive state of the content associated with a given
 DOI. It can comprise of these properties:
@@ -84,16 +84,16 @@ DOI. It can comprise of these properties:
 | archived_state | Yes | `dark` or `light` | Whether an archive copy is light or dark. Only valid if `archived_at` is present. |
 | archived_location | Yes | Any URL | Publicly accessible download location for the archive copy. Onlu valid if `archived_at` is present. |
 
-## Error
+### Error
 
 An error response contains a message with two required properties: `error_message` and `error_code`. `error_message` may contain a human readable explanation for any error (or, if that is not available, any additional information about the error). `error_code` must be set to the same value as the HTTP response code, which itself must be an HTTP error code in the 4xx or 5xx range.
 
-## Response Headers
+### Response Headers
 
 A HTTP response to the DOI query path may contain any headers, but must include a `Content-Type`
 header, and in the case of a redirect must include a `Location` header.
 
-## Response Examples
+### Response Examples
 
 Response for a DOI whose content has been received by the archive, but is currently dark:
 
@@ -138,7 +138,7 @@ An error response:
 	  }
 	}
 
-# Response Codes
+### Response Codes
 
 Responses to the DOI query path should incorporate all appropriate HTTP error codes.
 Clients should expect to receive any valid HTTP response code, including redirects

From 2501263b62976aec486ea89604fc9b5170787071 Mon Sep 17 00:00:00 2001
From: Karl Jonathan Ward 
Date: Mon, 13 Jan 2014 15:20:54 +0000
Subject: [PATCH 014/219] Rework JSON structure.

---
 archive_query_api.md | 108 +++++++++++++++++++++++++------------------
 1 file changed, 62 insertions(+), 46 deletions(-)

diff --git a/archive_query_api.md b/archive_query_api.md
index 7c1338d..4dcbdae 100644
--- a/archive_query_api.md
+++ b/archive_query_api.md
@@ -40,13 +40,9 @@ by a DOI.
 ## DOI Query Path
 
 A query API implementor must provide a publicly-accessible DOI query path. The path must
-either accept a DOI as a query parameter named `doi`:
+either accept a DOI as a query parameter named `doi` to a HTTP path `/doi/status`:
 
-    http://anarchive.org/status?doi={DOI}
-
-or, alternatively, accept a DOI as part of a HTTP path:
-
-    http://anarchive.org/status/{DOI}
+    http://anarchive.org/doi/status?doi={DOI}
 
 ### DOI Syntax
 
@@ -64,29 +60,29 @@ client's `Accept` header is always ignored, and the only valid `Content-Type` re
 is `application/json`, or `application/json; charset=UTF-8`, where the charset value may
 be set to any value appropriate for the response body.
 
-A valid JSON response contains a `message-type` and the `message` itself. Two message types
-are specified:
-
-| Type | Meaining |
-|------|----------|
-| archive | Response to a successful DOI query |
-| error | Response to a failed DOI query |
-
-### Archive
-
-An archive message represents the archive state of the content associated with a given
-DOI. It can comprise of these properties:
+A valid JSON response contains a `status`, `message` and `doi`:
 
 | Name | Optional? | Value | Description |
 |------|-----------|-------|-------------|
+| status | No | HTTP status code | Must match the HTTP response status code. |
+| message | No | Any string | A human readable error or status message. May be empty. |
 | doi | No | A DOI without any adornment (`doi:` etc.) e.g. `10.5555/12345678` | The query DOI an archive response refers to. |
-| archived_at | Yes | A valid [ISO 8601](http://en.wikipedia.org/wiki/ISO_8601) date or date and time string | Date or date and time at which a copy of content was received for archiving. Omission of this element indicates that no archive copy has been received for the query DOI. |
-| archived_state | Yes | `dark` or `light` | Whether an archive copy is light or dark. Only valid if `archived_at` is present. |
-| archived_location | Yes | Any URL | Publicly accessible download location for the archive copy. Onlu valid if `archived_at` is present. |
 
-### Error
+### Archived Copies
 
-An error response contains a message with two required properties: `error_message` and `error_code`. `error_message` may contain a human readable explanation for any error (or, if that is not available, any additional information about the error). `error_code` must be set to the same value as the HTTP response code, which itself must be an HTTP error code in the 4xx or 5xx range.
+A JSON response may also contain archive information about one or more archived copies. No
+`copies` element, or an empty `copies` element, indicates that no archive copy has been
+received for the query DOI.
+
+Each `copies` entry may contain:
+
+| Name | Optional? | Value | Description |
+|------|-----------|-------|-------------|
+| received_at | No | A valid [ISO 8601](http://en.wikipedia.org/wiki/ISO_8601) date or date and time string | Date or date and time at which a copy of content was received for archiving. |
+| state | No | `dark` or `light` | Whether an archive copy is light or dark. |
+| location | Yes | Any URL | Publicly accessible download location for the archive copy. |
+| content_version | Yes | `am` or `vor` | Indicates that the archive copy is specifically a copy of the author accepted manuscript (`am`) or publisher version of record (`vor`). |
+| content_type | Yes | Any valid MIME type | The content type of the archive copy. |
 
 ### Response Headers
 
@@ -98,44 +94,64 @@ header, and in the case of a redirect must include a `Location` header.
 Response for a DOI whose content has been received by the archive, but is currently dark:
 
     {
-	  "message-type": "archive",
-	  "message": {
-	    "doi": "10.5555/12345678"
-	    "archived_at": "2014-01-13T12:24Z",
-		"archived_state": "dark"
-      }
+      "status": 200,
+	  "message": "",
+      "doi": "10.5555/12345678",
+	  "copies": [
+	    {
+	      "received_at": "2014-01-13T12:24Z",
+		  "state": "dark",
+		  "content_version": "am",
+		  "content_type": "application/pdf"
+	    },
+		{
+		  "received_at": "2014-01-13T12:24Z",
+		  "state": "dark",
+		  "content_version": "vor",
+		  "content_type": "text/xml"
+	    }
+	  ]
 	}
 
 Response for a DOI whose content has not been received by the archive:
 
     {
-      "message-type": "archive",
-	  "message": {
-	    "doi": "10.5555/12345678"
-	  }
+      "status": 200,
+	  "message": ""
+	  "doi": "10.5555/12345678",
+	  "copies": []
 	}
 
 Response for a DOI whose content has been received by the archive and for which there
 has been a trigger event, making the content become light:
 
     {
-	  "message-type": "archive",
-	  "message": {
-        "doi": "10.5555/12345678",
-		"archived_at": "2014-01-13T12:24Z",
-		"archived_state": "light",
-		"archived_location": "http://anarchive.org/archive/10.5555/12345678"
-	  }
-	}
+      "status": 200,
+	  "message": "",
+      "doi": "10.5555/12345678",
+	  "copies": [
+	    {
+	      "received_at": "2014-01-13T12:24Z",
+		  "state": "dark",
+		  "content_version": "am",
+		  "content_type": "application/pdf",
+		  "location": "http://anarchive.org/content/am/10.5555/12345678.pdf"
+	    },
+		{
+		  "received_at": "2014-01-13T12:24Z",
+		  "state": "dark",
+		  "content_version": "vor",
+		  "content_type": "text/xml",
+          "location": "http://anarchive.org/content/vor/10.5555/12345678.xml"
+	    }
+	  ]
+  }
 
 An error response:
 
     {
-	  "message-type": "error",
-	  "message": {
-	    "error_message": "Upstream service is currently unavailable.",
-		"error_code": 506
-	  }
+	  "status": 506,
+	  "message": "Upstream service is currently unavailable."
 	}
 
 ### Response Codes

From ac738a3225d2c62658bc194b91aa5b1c4fcd18a6 Mon Sep 17 00:00:00 2001
From: Karl Jonathan Ward 
Date: Mon, 13 Jan 2014 15:21:50 +0000
Subject: [PATCH 015/219] Slight wording change.

---
 archive_query_api.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/archive_query_api.md b/archive_query_api.md
index 4dcbdae..e518c91 100644
--- a/archive_query_api.md
+++ b/archive_query_api.md
@@ -70,7 +70,7 @@ A valid JSON response contains a `status`, `message` and `doi`:
 
 ### Archived Copies
 
-A JSON response may also contain archive information about one or more archived copies. No
+A JSON response may also contain the archive state one or more archive copies. No
 `copies` element, or an empty `copies` element, indicates that no archive copy has been
 received for the query DOI.
 

From b54868b868095a4ee1002571cbb2e80937294a5c Mon Sep 17 00:00:00 2001
From: Karl Jonathan Ward 
Date: Mon, 13 Jan 2014 15:25:24 +0000
Subject: [PATCH 016/219] Link out to media type definition.

---
 archive_query_api.md | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/archive_query_api.md b/archive_query_api.md
index e518c91..0ae2c79 100644
--- a/archive_query_api.md
+++ b/archive_query_api.md
@@ -82,7 +82,7 @@ Each `copies` entry may contain:
 | state | No | `dark` or `light` | Whether an archive copy is light or dark. |
 | location | Yes | Any URL | Publicly accessible download location for the archive copy. |
 | content_version | Yes | `am` or `vor` | Indicates that the archive copy is specifically a copy of the author accepted manuscript (`am`) or publisher version of record (`vor`). |
-| content_type | Yes | Any valid MIME type | The content type of the archive copy. |
+| content_type | Yes | Any valid [media type](http://en.wikipedia.org/wiki/Internet_media_type) | The content type of the archive copy. |
 
 ### Response Headers
 
@@ -132,14 +132,14 @@ has been a trigger event, making the content become light:
 	  "copies": [
 	    {
 	      "received_at": "2014-01-13T12:24Z",
-		  "state": "dark",
+		  "state": "light",
 		  "content_version": "am",
 		  "content_type": "application/pdf",
 		  "location": "http://anarchive.org/content/am/10.5555/12345678.pdf"
 	    },
 		{
 		  "received_at": "2014-01-13T12:24Z",
-		  "state": "dark",
+		  "state": "light",
 		  "content_version": "vor",
 		  "content_type": "text/xml",
           "location": "http://anarchive.org/content/vor/10.5555/12345678.xml"

From 8e2134a030af609f63f5a52d1697a538d1bf3dca Mon Sep 17 00:00:00 2001
From: Karl Jonathan Ward 
Date: Mon, 13 Jan 2014 15:26:28 +0000
Subject: [PATCH 017/219] Minor tweak to example.

---
 archive_query_api.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/archive_query_api.md b/archive_query_api.md
index 0ae2c79..b7742aa 100644
--- a/archive_query_api.md
+++ b/archive_query_api.md
@@ -150,7 +150,7 @@ has been a trigger event, making the content become light:
 An error response:
 
     {
-	  "status": 506,
+	  "status": 504,
 	  "message": "Upstream service is currently unavailable."
 	}
 

From 11793ba411dcea2a6f17ca03e18cee71d77be44b Mon Sep 17 00:00:00 2001
From: Karl Jonathan Ward 
Date: Tue, 4 Feb 2014 12:45:47 +0000
Subject: [PATCH 018/219] Update archive_query_api.md

---
 archive_query_api.md | 13 +++++++------
 1 file changed, 7 insertions(+), 6 deletions(-)

diff --git a/archive_query_api.md b/archive_query_api.md
index b7742aa..61eba98 100644
--- a/archive_query_api.md
+++ b/archive_query_api.md
@@ -6,6 +6,7 @@ Archive Arrangement Query API
 | Date | Changes |
 |------|---------|
 | 2014-01-13 | Initial version |
+| 2014-02-04 | Fix some typos |
 
 ## Background
 
@@ -39,8 +40,7 @@ by a DOI.
 
 ## DOI Query Path
 
-A query API implementor must provide a publicly-accessible DOI query path. The path must
-either accept a DOI as a query parameter named `doi` to a HTTP path `/doi/status`:
+A query API implementor must provide a publicly-accessible DOI query path. The path must accept a DOI as a query parameter named `doi` to a HTTP path `/doi/status`:
 
     http://anarchive.org/doi/status?doi={DOI}
 
@@ -110,8 +110,8 @@ Response for a DOI whose content has been received by the archive, but is curren
 		  "content_version": "vor",
 		  "content_type": "text/xml"
 	    }
-	  ]
-	}
+      ]
+    }
 
 Response for a DOI whose content has not been received by the archive:
 
@@ -151,8 +151,9 @@ An error response:
 
     {
 	  "status": 504,
-	  "message": "Upstream service is currently unavailable."
-	}
+	  "message": "Upstream service is currently unavailable.",
+	  "doi": "10.5555/12345678"
+    }
 
 ### Response Codes
 

From e326f82f07d5b6c5e82ae9511e3341a211e4fbd8 Mon Sep 17 00:00:00 2001
From: Karl Jonathan Ward 
Date: Mon, 10 Feb 2014 11:45:01 +0000
Subject: [PATCH 019/219] Update funder_kpi_api.md

---
 funder_kpi_api.md | 1 +
 1 file changed, 1 insertion(+)

diff --git a/funder_kpi_api.md b/funder_kpi_api.md
index e9b9179..333aeac 100644
--- a/funder_kpi_api.md
+++ b/funder_kpi_api.md
@@ -15,6 +15,7 @@
 - v10: 2013-12-13, /types routes, type filter, issn filter
 - v11: 2013-12-14, indexed timestamps, has-archive and archive implemented
 - v12: 2014-01-06, directory filter
+- v13: 2014-02-10, new `/members`, `/publishers` becomes `/prefixes`, new `member` filter, `publisher` filter becomes `prefix`
 
 ## Background
 

From 0955e6b74e966a77e2b0050fa8ae0873769815c9 Mon Sep 17 00:00:00 2001
From: Karl Jonathan Ward 
Date: Mon, 10 Feb 2014 11:51:45 +0000
Subject: [PATCH 020/219] Update for /members and /prefixes.

---
 funder_kpi_api.md | 13 +++++++++----
 1 file changed, 9 insertions(+), 4 deletions(-)

diff --git a/funder_kpi_api.md b/funder_kpi_api.md
index 333aeac..645649a 100644
--- a/funder_kpi_api.md
+++ b/funder_kpi_api.md
@@ -105,7 +105,7 @@ 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)
-| `/publishers` | returns a list of all publishers|
+| `/members` | returns a list of all CrossRef members (mostly publishers) |
 | `/types`      | returns a list of valid work types | 
 
 
@@ -116,7 +116,8 @@ Resource components can be used in conjunction with identifiers to retrieve the
 |:----------------------------|:----------------------------------|
 | `/works/{doi}`              | returns metadata for the specified CrossRef DOI. |
 | `/funders/{funder_id}`      | returns metadata for specified funder **and** its suborganizations |
-| `/publishers/{owner_prefix}` | returns metadata for the specified publisher |
+| `/prefixes/{owner_prefix}` | returns metadata for the DOI owner prefix |
+| `/members/{member_id}` | returns metadata for a CrossRef member |
 | `/types/{type_id}` | returns information about a metadata work type |
 
 ### Combining resource components
@@ -128,7 +129,8 @@ The works component can be appended to other resources.
 | `/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}/works` | returns list of works of type `type` |
-| `/publishers/{owner_prefix}/works` | returns list of works associated with specified `owner_prefix` |
+| `/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) |
 
 
 ## Parameters
@@ -181,7 +183,8 @@ Filters allow you to narrow queries. All filter results are lists.  The followin
 | filter     | possible values | description|
 |:-----------|:----------------|:-----------|
 | `funder` | `{funder_id}` | metadata which include the `{funder_id}` in FundRef data |
-| `publisher` | `{owner_prefix}` | metadata belongs to published identified by `{owner_prefix}` (e.g. `10.1016` ) |
+| `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 |
 | `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}` |
@@ -214,6 +217,8 @@ Filters allow you to narrow queries. All filter results are lists.  The followin
 
 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.
+
 ### Notes on dates
 
 Note that dates in filters should always be of the form `YYYY-MM-DD`. Also not 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. 

From b892711c2022de081d8d9351ced700b4ef7c8c15 Mon Sep 17 00:00:00 2001
From: Karl Jonathan Ward 
Date: Mon, 10 Feb 2014 11:52:36 +0000
Subject: [PATCH 021/219] Update funder_kpi_api.md

---
 funder_kpi_api.md | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/funder_kpi_api.md b/funder_kpi_api.md
index 645649a..e9cadd8 100644
--- a/funder_kpi_api.md
+++ b/funder_kpi_api.md
@@ -97,7 +97,8 @@ Major resource components supported by the CrossRef API are:
 
 - works
 - funders
-- publishers
+- members
+- prefixes
 
 These can be used alone like this
 

From 4c22e1c3cec98aec203ac5ff4dc8643bb00430a3 Mon Sep 17 00:00:00 2001
From: Karl Jonathan Ward 
Date: Fri, 14 Feb 2014 11:18:49 +0000
Subject: [PATCH 022/219] Document has-funder filter.

---
 funder_kpi_api.md | 14 +++++++++-----
 1 file changed, 9 insertions(+), 5 deletions(-)

diff --git a/funder_kpi_api.md b/funder_kpi_api.md
index e9cadd8..300add7 100644
--- a/funder_kpi_api.md
+++ b/funder_kpi_api.md
@@ -16,6 +16,7 @@
 - v11: 2013-12-14, indexed timestamps, has-archive and archive implemented
 - v12: 2014-01-06, directory filter
 - v13: 2014-02-10, new `/members`, `/publishers` becomes `/prefixes`, new `member` filter, `publisher` filter becomes `prefix`
+- v14: 2014-02-14, new `has-funder` filter.
 
 ## Background
 
@@ -76,14 +77,16 @@ Lists results can contain multiple entries. Searching or filtering typically ret
 - Items, which will will contain the items matching the query or filter. 
 
 
-Note that the "message-type" returned will differ from the mime-type. There are six message-types:
+Note that the "message-type" returned will differ from the mime-type:
 
 - funder (singleton)
-- publisher (singleton)
+- prefix (singleton)
+- member (singleton)
 - work (singleton)
-- work-result-list (list)
-- funder-result-list (list)
-- publisher-result-list (list) 
+- work-list (list)
+- funder-list (list)
+- prefix-list (list)
+- member-list (list)
 
 
 Normally, and API list result will return both the summary and the items. If you want to just retrieve the summary, you can do so by specifying that the number of rows returned should be zero. 
@@ -183,6 +186,7 @@ Filters allow you to narrow queries. All filter results are lists.  The followin
 
 | filter     | possible values | description|
 |:-----------|:----------------|:-----------|
+| `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 |

From e25b38c5e98170969cb1fb2ea624354372ad8f4e Mon Sep 17 00:00:00 2001
From: Karl Jonathan Ward 
Date: Fri, 14 Feb 2014 15:20:08 +0000
Subject: [PATCH 023/219] Update funder_kpi_api.md

---
 funder_kpi_api.md | 12 ++++++------
 1 file changed, 6 insertions(+), 6 deletions(-)

diff --git a/funder_kpi_api.md b/funder_kpi_api.md
index 300add7..c0f0c36 100644
--- a/funder_kpi_api.md
+++ b/funder_kpi_api.md
@@ -271,15 +271,15 @@ Note that when you use the `sample` parameter, the `rows` and `offset` parameter
 
 **All works published by owner prefix `10.1016` in January 2010**
 
-    http://api.crossref.org/publishers/10.1016/works?filter=from-pub-date:2010-01,until-pub-date:2010-01
+    http://api.crossref.org/prefixes/10.1016/works?filter=from-pub-date:2010-01,until-pub-date:2010-01
 
-**All works funded by funder_id that have a CC-BY license**
+**All works funded by `10.13039/100000001` that have a CC-BY license**
 
-    http://api.crossref.org/publishers/10.5555/works?filter=license.url:http://creativecommons.org/licenses/by/3.0/deed.en_US
+    http://api.crossref.org/funders/10.13039/100000001/works?filter=license.url:http://creativecommons.org/licenses/by/3.0/deed.en_US
 
 **All works published by owner prefix 10.5555 from February 2010 to February 2013 that have a CC-BY license**
 
-    http://api.crossref.org/publishers/10.5555/works?filter=license.url:http://creativecommons.org/licenses/by/3.0/deed.en_US,from-pub-date:2010-02,until-pub-date:2013-02
+    http://api.crossref.org/prefixes/10.5555/works?filter=license.url:http://creativecommons.org/licenses/by/3.0/deed.en_US,from-pub-date:2010-02,until-pub-date:2013-02
 
 **All works funded by `10.13039/100000015` where license = CC-BY and embargo <= 365 days**
 
@@ -287,9 +287,9 @@ Note that when you use the `sample` parameter, the `rows` and `offset` parameter
 
 Note that the filters for license URL and maximum license embargo period (license.url and license.delay) combine to filter each document's metadata for a license with both of these properties.
 
-**All works funded by X where the archive partner listed = 'LOCKSS'**
+**All works where the archive partner listed = 'LOCKSS'**
 
-Coming soon.
+    http://api.crossref.org/works?filter?archive=LOCKSS
 
 
 ## Versioning

From fc8bc21a9b68277dba7ce78526a0fcf9e63f68d1 Mon Sep 17 00:00:00 2001
From: Karl Jonathan Ward 
Date: Thu, 27 Feb 2014 15:49:09 +0000
Subject: [PATCH 024/219] Document /licenses route

---
 funder_kpi_api.md | 13 +++++++++++++
 1 file changed, 13 insertions(+)

diff --git a/funder_kpi_api.md b/funder_kpi_api.md
index c0f0c36..d196b43 100644
--- a/funder_kpi_api.md
+++ b/funder_kpi_api.md
@@ -17,6 +17,7 @@
 - v12: 2014-01-06, directory filter
 - v13: 2014-02-10, new `/members`, `/publishers` becomes `/prefixes`, new `member` filter, `publisher` filter becomes `prefix`
 - v14: 2014-02-14, new `has-funder` filter.
+- v15: 2014-02-27, new `/licenses` route
 
 ## Background
 
@@ -111,6 +112,7 @@ These can be used alone like this
 | `/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) |
 | `/types`      | returns a list of valid work types | 
+| `/licenses`  | return a list of licenses applied to works in CrossRef metadata |
 
 
 ### Resource components and identifiers
@@ -290,7 +292,18 @@ Note that the filters for license URL and maximum license embargo period (licens
 **All works where the archive partner listed = 'LOCKSS'**
 
     http://api.crossref.org/works?filter?archive=LOCKSS
+    
+**All members with `hind` in their name (e.g. Hindawi)**
+
+    http://api.crossref.org/members?query=hind
+    
+**All licenses linked to works published by Elsevier**
+
+    http://api.crossref.org/licenses?filter=member:78
+    
+**All licenses applied to works published in the journal `Pathology Research International`**
 
+    http://api.crossref.org/licenses?filter=issn:2090-8091
 
 ## Versioning
 

From c36067369ca0e7972628999609e89dc033f70b25 Mon Sep 17 00:00:00 2001
From: Geoffrey Bilder 
Date: Fri, 28 Feb 2014 16:16:06 +0000
Subject: [PATCH 025/219] added koans. deleted HTML

---
 ...syndication_through_crossref_metadata.html | 271 -------
 funder_kpi_api.html                           | 685 ------------------
 funder_kpi_metadata_best_practice.html        | 530 --------------
 3 files changed, 1486 deletions(-)
 delete mode 100644 content_syndication_through_crossref_metadata.html
 delete mode 100644 funder_kpi_api.html
 delete mode 100644 funder_kpi_metadata_best_practice.html

diff --git a/content_syndication_through_crossref_metadata.html b/content_syndication_through_crossref_metadata.html
deleted file mode 100644
index d714eeb..0000000
--- a/content_syndication_through_crossref_metadata.html
+++ /dev/null
@@ -1,271 +0,0 @@
-  
-
-
-  
-  
-  content_syndication_through_crossref_metadata
-  
-  
-
-
-
-  
    
-      
    Content Syndication Through CrossRef Metadata
    
-
-
    Version History
    
-
-
      
-
    • V1 2014–01–08, Initial draft
      • 
-
    
-
-
    The Problem
    
-
-
    There is concern that the CrossRef schema does not give enough information to users about which resources are appropriate for different user classes and/or applications. For example, a publisher might want to be able to provide different lists of resources for the following use cases:
    
-
-
      
-
    • A human subscriber accessing the content to read 
      • 
-
    • A human non-subscriber accessing the content to read 
      • 
-
    • A human from an entitled funding agency accessing the content to read
      • 
-
    • A bot run by a subscriber accessing the content to TDM
      • 
-
    • A bot run by a non-subscriber accessing the content to TDM
      • 
-
    • A bot run by an entitled funding agency accessing the content to TDM
      • 
-
    • A bot run by a subscriber accessing the content to syndicate
      • 
-
    • A bot run by a non-subscriber accessing the content to syndicate
      • 
-
    • A bot run by an entitled funding agency accessing the content to syndicate
      • 
-
    
-
-
    In the above cases, the content in question might or be either “restricted” (e.g. requiring a subscription to access) or “unrestricted” (open access, free). Furthermore, any restrictions may be time-boxed via embargoes. This effectively means that their are sub-cases where the desired behavior might change depending on when the user (bot or human) tries to access the content.
    
-
-
    So for the above use cases the publisher might want the user to select a resource that points to either:
    
-
-
      
-
    • A human readable landing page on the publisher’s main website.
      • 
-
    • A human readable representation of the VOR (e.g. PDF, HTML, etc.) on the publisher’s main website.
      • 
-
    • A human readable representation of the AAM (e.g. PDF, HTML, etc.) on the publisher’s main website.
      • 
-
    • A machine readable representation of the VOR (e.g. XML, Plain Text) on the publisher’s TDM server
      • 
-
    • A machine readable representation of the AAM (e.g. XML, Plain Text) on the publisher’s TDM server
      • 
-
    • A human readable representation of the VOR (e.g. PDF, HTML, etc.) on the publisher’s syndication server.
      • 
-
    • A human readable representation of the AAM (e.g. PDF, HTML, etc.) on the publisher’s syndication server.
      • 
-
    
-
-
    Selecting the appropriate resource would seem to hinge on three criteria:
    
-
-
      
-
    • Is the agent a human or a bot?
      • 
-
    • Is the content under restricted access? For example, is a subscription needed?, is the content currently under embargo?
      • 
-
    • is the agent entitled at this particular time?
      • 
-
    • What is the desired application? Viewing, indexing, syndication, tdm?
      • 
-
    
-
-
    We have used the term “BAV” to describe the “Best Available Version.”- where “version” refers to the JATS version of a document (i.e. AAM, VOR). The idea is that some versions of the document (e.g. VOR) may be under restricted access (e.g. under embargo, require a subscription) and are thus “unavailable” to certain classes of user, while other versions of the document (e.g. AAM) are not under restrictions and are thus “available” to the respective class of user.
    
-
-
    But the above use-cases introduce another facet that may need to be considered when selecting a resource- the “Appropriate Application Resource” (AAR). That is, the use-cases above imply that publishers might want to direct users at resources pointing to systems that are optimized to support a particular application. For example, a publisher might have a server that is reserved for search engines, or for syndication partners, etc. 
    
-
-
    Providing Hints For Selecting a BAV
    
-
-
    The normative HTTP mechanism to handle these requirements technically, would be to use content negotiation. That is, an agent could request a resource using a GET and be shown the options for different available versions of the resource in the response headers. The user agent would then select the BAV/AAR from the options presented in the publisher’s response. In other words, ideally the system would work the same way that content negotiation works for languages or for browser feature sets.
    
-
-
    However, CrossRef recognizes that, in the short/medium term, it would be impractical to expect all of our members to integrate such content negotiation in their publishing sites. Thus we have added the ability for publisher to record attributes of the resource that one would normally use content negotiation for in selecting a BAV. Specifically, we have added the following two attributes to the resource element:
    
-
-
      
-
    • mime_type
      • 
-
    • content_version
      • 
-
    
-
-
    This allows the publisher to record resources for all the combinations of representation (PDF,HTML, Etc.) and version (VOR, AAM) that the publisher supports. In turn, the user can use these attributes to determine a-priori (i.e. without having to do an HTTP query for content negotiation) which versions of the content exist. However, it does give the user any information to a-priori determine which versions of the content are likely to be available. In other words, just because the HTTP URI of a particular representation of a particular version of the content is listed, that doesn’t mean that the user is guaranteed to be able to access the resource. The resource might require a subscription, it might be under embargo, etc.
    
-
-
    The addition of the AccessIndicators section to the CrossRef schema provides a mechanism that allows publishers to provide resource-specific information about the purported accessibility of the content pointed to by the resource using extended versions of the NISO-recommended <license_reference> and <free-to-read> elements. The //AccessIndicators/license_ref element has been extended with an “applies_to” attribute which can be used to map specific licenses (identified by HTTP URIs) to specific resources based on their content_version. So, for example, this enables a publisher to link one license to the resource that points to the VOR of the content and a different license to the resource that points to the AAM of the content. Similarly, the publisher will be able to map the //AccessIndicators/free-to-read element to specific resources identified by the content_version attribute in order to indicate that the content pointed to by a resource is available to “view” without any payment or registration preconditions.
    
-
-
    The <license_ref> element can also include a start_date attribute, which can be used to indicate when a license takes effect. This, in turn, can be used to record simple embargo information and to map that information to a specific version of the <resource> identified by the content_type attribute.
    
-
-
    For example, the following records that the VOR of the content is under a proprietary license from its date of publication on February 3, 2014 and that it is under a CC-BY license a year later on February 3, 2015 *and that the AAM of the content is available from the date of publication under a CC-BY license:
    
-
-
    <resource content_version="vor">http://www.psychoceramics.org/fulltext/vor/10.5555/12345678</resource>
-<resource content_version="am">http://www.psychoceramics.org/fulltext/am/10.5555/12345678</resource>
-<!-- … -->
-<license_ref applies_to="VOR" start_date="2014-02-03">http://www.psychoceramics.org/license_v1.html</license_ref>
-<license_ref applies_to="VOR" start_date="2015-02-03">http://creativecommons.org/licenses/by/3.0/deed.en_US</license_ref>
-<license_ref applies_to="AAM" start_date="2014-02-03">http://creativecommons.org/licenses/by/3.0/deed.en_US</license_ref>
-
    
-
-
    The addition of the AccessIndicators allows the publisher to indicate not only what versions of the resource exist , but also for the publisher to provide a mechanism for the user to determine a-priori (without doing an HTTP get for content negotiation) which versions of the resource are likely to be available. In short, the combination of //AccessIndicator elements and //collection/resource elements allows the user to determine the BAV. 
    
-
-
    Providing Hints For Selecting a AAR
    
-
-
    But this still leaves us with the question of how to provide the publisher to provide the user with hints as to which version of a resource is appropriate for a particular application. So-far we have identified the following applications:
    
-
-
    1) Viewing (e.g. on the publisher’s web site, via landing page, etc.)
-2) Indexing (e.g. for search engines, etc.)
    
-
-
    Currently we already have three existing mechanisms for labeling different ‘applications’ of the resource. 
    
-
-
    The first mechanism is implicit. That is /doi_data/resource attributes have normatively recorded a link to the publisher landing page, from which the human reader can get a “viewable” version of the resource. 
    
-
-
    The second two are encoded in the the property attribute of the <collection> container element. We currently support several values for this property, including crawler-based which was intended to be used to identify resources for search engines (i.e. indexing) and text-mining which has been introduced for resources designed for TDM bots. What seems to be missing is a value for “syndication.” If we were to add a syndication attribute value then publishers would be able to record /collection/resource elements that meet all the use-cases identified above. 
    
-
-
    ## Limitations of proposed system
    
-
-
    The hints provided in CrossRef metadata are just that, hints. There is nothing that CrossRef can do to force users to select an particular resource appropriate to their application. Thus, it is still going to be the responsibility of the publisher to check requests and to route them appropriately. 
    
-
-
-
-
-    
    
-
-
\ No newline at end of file
diff --git a/funder_kpi_api.html b/funder_kpi_api.html
deleted file mode 100644
index 556e785..0000000
--- a/funder_kpi_api.html
+++ /dev/null
@@ -1,685 +0,0 @@
-  
-
-
-  
-  
-  funder_kpi_api
-  
-  
-
-
-
-  
    
-      
    CrossRef APIs to support key performance indicators (KPIs) for funding agencies
    
-
-
    Version History
    
-
-
      
-
    • V1: 2013–09–08, first draft.
      • 
-
    • V2: 2013–09–24, reference platform deployed
      • 
-
    • v3: 2013–09–25, reworked filters. Added API versioning doc
      • 
-
    • v4: 2013–09–25, more filter changes.
      • 
-
    • v5: 2013–09–27, doc mime-type and message-type relationship
      • 
-
    • v6: 2013–10–01, updated sample & added examples with filters
      • 
-
    • v6: 2013–10–01, corrected warning date
      • 
-
    • v7: 2013–10–02, fixed typos
      • 
-
    • v8: 2013–10–17, updated warning. Added email address
      • 
-
    • v9: 2013–12–13, update example urls
      • 
-
    
-
-
    Background
    
-
-
    See the document, CrossRef metadata best practice to support key performance indicators (KPIs) for funding agencies, for background.
    
-
-
    Warning
    
-
-
    The API described here is in alpha. If you encounter problems with the API or the documentation, please report them to:
    
-
-
    
-
    
-
-
-
-
    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 convention:
    
-
-
    http://doi.crossref.org/doiRA/{doi}
    
-
-
    So testing the following CrossRef DOI:
    
-
-
    10.1037/0003-066X.59.1.29
    
-
-
    Will return the following result:
    
-
-
    [
-    {
-         DOI: "10.1037/0003-066X.59.1.29",
-         RA: "CrossRef"
-    }
-]
-
    
-
-
    If you use any of the API calls listed below with a non-CrossRef DOI, you will get a 404 HTTP status response with the message “non-CrossRef DOI.”
    
-
-
    Results Overview
    
-
-
    All results are returned in JSON. There are two general types of results:
    
-
-
      
-
    • Singletons
      • 
-
    • Lists
      • 
-
    
-
-
    The mime-type for API results is application/vnd.crossref-api-message+json 
    
-
-
    Singletons
    
-
-
    Singletons are single results. Retrieving metadata for a specific identifier (e.g. DOI, ISSN, funder_identifier) typically returns in a singleton result.
    
-
-
    Lists
    
-
-
    Lists results can contain multiple entries. Searching or filtering typically returns a list result. A list has two parts:
    
-
-
      
-
    • Summary, which include the following information:
-
-
        
-
      • status (e.g. “ok”, error)
        • 
-
      • message-type (e.g. “work-list” )
        • 
-
      • message-version (e.g. 1.0.0 )
        • 
-
      • 
-
    • Items, which will will contain the items matching the query or filter.
      • 
-
    
-
-
    Note that the “message-type” returned will differ from the mime-type. There are six message-types:
    
-
-
      
-
    • funder (singleton)
      • 
-
    • publisher (singleton)
      • 
-
    • work (singleton)
      • 
-
    • work-result-list (list)
      • 
-
    • funder-result-list (list)
      • 
-
    • publisher-result-list (list)
      • 
-
    
-
-
    Normally, and API list result will return both the summary and the items. If you want to just retrieve the summary, you can do so by specifying that the number of rows returned should be zero. 
    
-
-
    Sort order
    
-
-
    If the API call includes a query, then the sort order will be by the relevance score. If no query is included, then the sort order will be by DOI update date.
    
-
-
    Resource Components
    
-
-
    Major resource components supported by the CrossRef API are:
    
-
-
      
-
    • works
      • 
-
    • funders
      • 
-
    • publishers
      • 
-
    
-
-
    These can be used alone like this
    
-
-
----
-
-
-
-	
-	
-
-
-
-
-
-	
-	
-
-
-	
-	
-
-
-	
-	
-
-
-
    



    resourcedescription
    /worksreturns a list of all works (journal articles, conference proceedings, books, components, etc), 20 per page.
    /fundersreturns a list of all funders in the FundRef Registry
    /publishersr eturns a list of all publishers.
    
-
    Resource components and identifiers
    
-
-
    Resource components can be used in conjunction with identifiers to retrieve the metadata for that identifier.
    
-
-
----
-
-
-
-	
-	
-
-
-
-
-
-	
-	
-
-
-	
-	
-
-
-	
-	
-
-
-
    



    resourcedescription
    /works/{doi}returns metadata for the specified CrossRef DOI.
    /funders/{funder_id}returns metadata for specified funder and its suborganizations
    /publishers/{owner_prefix}returns metadata for the specified publisher.
    
-
    Combining resource components
    
-
-
    The works component can be appended to other resources.
    
-
-
----
-
-
-
-	
-	
-
-
-
-
-
-	
-	
-
-
-	
-	
-
-
-	
-	
-
-
-
    



    resourcedescription
    /works/{doi}returns information about the specified CrossRef DOI
    /funders/{funder_id}/worksreturns list of works associated with the specified funder_id
    /publishers/{owner_prefix}/worksreturns list of works associated with specified owner_prefix
    
-
    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.
    
-
-
----
-
-
-
-	
-	
-
-
-
-
-
-	
-	
-
-
-	
-	
-
-
-	
-	
-
-
-	
-	
-
-
-	
-	
-
-
-
    



    parameterdescription
    querylimited DisMax query terms
    filter={filter_name}:{value}filter results by specific fields
    rows={#}results per per page
    offset={#}result offset
    sample={#}return random N results
    
-
    Multiple filters can be specified by separating name:value pairs with a comma:
    
-
-
    http://api.crossref.org/works?filter=has-orcid:true,from-pub-date:2004-04-04
-
    
-
-
    Example query using URI parameters
    
-
-
    http://api.crossref.org/funders/100000015/works?query=global+state&filter=has-orcid:true&rows=1
-
    
-
-
    Example query using JSON in body of GET request
    
-
-
    Note that if you include a body in your GET request, any URI parameters will be ignored. In short, you cannot mix URI parameters and JSON queries.
    
-
-
    To use the API using JSON, pass the JSON in the body of the HTTP GET request like this:
    
-
-
    curl -X GET -H "Content-Type: application/json" -d '{"query": "psychoceramics", "offset": 40, "rows": 20, "filter": {"has-orcid": true, "publisher": "10.5555"}}'  http://api.crossref.org/works
-
    
-
-
    Queries
    
-
-
    Queries support a subset of DisMax, so, for example you can refine queries as follows.
    
-
-
    Works that include “renear” but not “ontologies”
    
-
-
    http://api.crossref.org/works?query=renear+-ontologies
-
    
-
-
    or using JSON
    
-
-
    curl -X GET -H "Content-Type: application/json" -d '{"query": "renear -ontologies"}'  http://api.crossref.org/works
-
    
-
-
    Filter Names
    
-
-
    Filters allow you to narrow queries. All filter results are lists. The following filters are supported:
    
-
-
-----
-
-
-
-	
-	
-	
-
-
-
-
-
-	
-	
-	
-
-
-	
-	
-	
-
-
-	
-	
-	
-
-
-	
-	
-	
-
-
-	
-	
-	
-
-
-	
-	
-	
-
-
-	
-	
-	
-
-
-	
-	
-	
-
-
-	
-	
-	
-
-
-	
-	
-	
-
-
-	
-	
-	
-
-
-	
-	
-	
-
-
-	
-	
-	
-
-
-	
-	
-	
-
-
-	
-	
-	
-
-
-	
-	
-	
-
-
-	
-	
-	
-
-
-	
-	
-	
-
-
-
    




    filterpossible valuesdescription
    funder{funder_id}metadata which include the {funder_id} in FundRef data
    publisher{owner_prefix}metadata belongs to published identified by {owner_prefix} (e.g. 10.1016 )
    from-update-date{date}metadata updated since (inclusive) {date}
    until-update-date{date}metadata updated before (inclusive) {date}
    from-pub-date{date}metadata where published date is since (inclusive) {date}
    until-pub-date{date}metadata where published date is before (inclusive) {date}
    has-licensemetadata that includes any <license_ref> elements.
    license.url{url}metadata where <license_ref> value equals {url}
    license.version{string}metadata where the <license_ref>’s applies_to attribute is {string}
    license.delay{integer}metadata where difference between publication date and the <license_ref>’s start_date attribute is <= {integer} (in days)
    has-full-textmetadata that includes any full text <resource> elements.
    full-text.version{string}metadata where <resource> element’s content_version attribute is {string}.
    full-text.type{mime_type}metadata where <resource> element’s content_type attribute is {mime_type} (e.g. application/pdf).
    public-referencesmetadata where publishers allow references to be distributed publically. [1]
    has-archivemetadata which include name of archive partner[1]
    archive{string}metadata which where value of archive partner is {string}[1]
    has-orcidmetadata which includes one or more ORCIDs
    orcid{orcid}metadata where <orcid> element’s value = {orcid}
    
-
    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. 
    
-
-
    Notes on dates
    
-
-
    Note that dates in filters should always be of the form YYYY-MM-DD. Also not 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. 
    
-
-
    Result controls
    
-
-
    You can control the delivery and selection results using the rows, offset and sample parameters. 
    
-
-
    Rows
    
-
-
    Normally, results are returned 20 at a time. You can control the number of results returns by using the rows parameter. To limit results to 5, for example, you could do the following:
    
-
-
    http://api.crossref.org/works?query=allen+renear&rows=5
-
    
-
-
    If you would just like to get the summary of the results, you can set the rows to 0 (zero).
    
-
-
    http://api.crossref.org/works?query=allen+renear&rows=0
-
    
-
-
    The maximum number rows you can ask for in one query is 1000.
    
-
-
    Offset
    
-
-
    The number of returned items is controlled by the rows parameter, but you can select the offset into the result list by using the offset parameter. So, for example, to select the second set of 5 results (i.e. results 6 through 10), you would do the following:
    
-
-
    http://api.crossref.org/works?query=allen+renear&rows=5&offset=5
-
    
-
-
    Sample
    
-
-
    Being able to select random results is useful for both testing and sampling. You can use the sample parameter to retrieve random results. So, for example, the following select 10 random works:
    
-
-
    http://api.crossref.org/works?sample=10
-
    
-
-
    Note that when you use the sample parameter, the rows and offset parameters are ignored.
    
-
-
    Example Queries
    
-
-
    All works published by owner prefix 10.1016 in January 2010
    
-
-
    http://api.crossref.org/publishers/10.1016/works?filter=from-pub-date:2010-01,until-pub-date:2010-01
-
    
-
-
    All works funded by funder_id that have a CC-BY license
    
-
-
    http://api.crossref.org/publishers/10.5555/works?filter=license.url:http://creativecommons.org/licenses/by/3.0/deed.en_US
-
    
-
-
    All works published by owner prefix 10.5555 from February 2010 to February 2013 that have a CC-BY license
    
-
-
    http://api.crossref.org/publishers/10.5555/works?filter=license.url:http://creativecommons.org/licenses/by/3.0/deed.en_US,from-pub-date:2010-02,until-pub-date:2013-02
-
    
-
-
    All works funded by 10.13039/100000015 where license = CC-BY and embargo <= 365 days
    
-
-
    http://api.crossref.org/funders/10.13039/100000015/works?filter=license.url:http://creativecommons.org/licenses/by/3.0/deed.en_US,license.delay:365
-
    
-
-
    Note that the filters for license URL and maximum license embargo period (license.url and license.delay) combine to filter each document’s metadata for a license with both of these properties.
    
-
-
    All works funded by X where the archive partner listed = ‘LOCKSS’
    
-
-
    Coming soon.
    
-
-
    Versioning
    
-
-
    In theory, the syntax of the API can vary independently of the result representations. In practice, major version changes in either will require changes to API clients and so versioning of the API will apply to both the API syntax and the result representation.
    
-
-
    The API uses a semantic versioning scheme whereby the version number is divided into three parts delimited by periods. The first number represents the “major” release number. The second represents a “minor” release number and the third represents an “internal” release number. 
    
-
-
    Version 1.20.31
-        ^  ^  ^
-        |  |  |
-    major  |  |
-       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. 
    
-
-
    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.
    
-
-
    Adding syntax options or metadata to representations will normally be backwards compatible and will thus normally only trigger minor version changes. Renaming or restructuring syntax options of metadata tends not to be backward compatible and will thus typically trigger major version changes
    
-
-
    How to manage API versions
    
-
-
    If you need to tie your implementation to a specific major version of the API, you can do so by using content-negotiation and specifying the version of the API in the ACCEPT header as follows:
    
-
-
     application/vnd.crossref-api-message+json; version=1.0
-
    
-
-
    Minor version numbers will be ignored in ACCEPT headers as they are by definition backwards compatible.
    
-
-
    If you omit a specific version in your ACCEPT header, the system will default to using the latest version of the API. 
    
-
-
    Note that requesting a version of the API via content type is not yet supported.
    
-
-
    Error messages
    
-
-
    There will be no errors, and therefor error messages will be unnecessary. But seriously… coming soon.
    
-
-
-
-
-
-
    
-
    
-
      
-
-
    1. 
-
      Not implemented yet.  ↩
      
-
      2. 
-
-
    
-
    
-
-    
    
-
-
\ No newline at end of file
diff --git a/funder_kpi_metadata_best_practice.html b/funder_kpi_metadata_best_practice.html
deleted file mode 100644
index 0b1f961..0000000
--- a/funder_kpi_metadata_best_practice.html
+++ /dev/null
@@ -1,530 +0,0 @@
-  
-
-
-  
-  
-  funder_kpi_metadata_best_practice
-  
-  
-
-
-
-  
    
-      
    CrossRef metadata best practice to support key performance indicators (KPIs) for funding agencies
    
-
-
    Version History
    
-
-
      
-
    • V01: 2013–09–08, first draft.
      • 
-
    • V02: 2013–09–09, add examples + links.
      • 
-
    • V03: 2013–09–10, adjust title. Correct typos.
      • 
-
    • V04: 2013–09–12, changed AAM to AM.
      • 
-
    • V05: 2013–09–18, incorporated corrections, suggestions from D. Shotton.
      • 
-
    • V06: 2013–09–23, added <free-to-read> element info. Updated warning.
      • 
-
    • V07: 2013–09–24, emphasize that publishers must deposit funder identifiers, when they exist in the FundRef Registry.
      • 
-
    • V08: 2013–11–04, Added FAQ about schema interpretation and usage
      • 
-
    • V09: 2013–12–02, Added XML deposit examples
      • 
-
    • v10: 2013–12–03, Updated <free-to-read/> element documentation to reflect latest NISO work. Added information about licensing CrossRef metadata to FAQ (hint, no license required for free APIs). Added labs email address. Changed formatting.
      • 
-
    • v11: 2013–12–11, Added third party archive arrangements section. Updated examples to include archive locations.
      • 
-
    
-
-
    Warning
    
-
-
    As of 2013–12–03 the <free-to-read> element has not yet been incorporated into the CrossRef deposit schema.
    
-
-
    If you encounter problems with the API or the documentation, please report them to:
    
-
-
    
-
    
-
-
-
-
    Background
    
-
-
    Funding agencies and publishers are interested in being able to measure Key Performance Indicators (KPIs) related to mandates such the February 22nd OSTP memo on Public Access to the Results of Federally Funded Research.
-CrossRef is extending its FundRef Application Programming Interfaces (APIs) to enable funding agencies and publishers to query CrossRef metadata in support of generating such KPIs. Organisations such as CHORUS and SHARE can make use of these APIs in order to create KPI Dashboards measuring, amongst other things:
    
-
-
      
-
    1. Publications relating to research funded by particular agencies.
      2. 
-
    2. The licenses under which said publications have been released.
      3. 
-
    3. The location of the full text of the Best Available Version (BAV) for said publications for both reading and Text & Data Mining (TDM) applications.
      4. 
-
    4. The long-term preservation arrangements that have been made for the VOR of said publications.
      5. 
-
    
-
-
    The CrossRef extended APIs, of course, will only work if publishers supply the appropriate metadata. This document outlines the metadata that publishers will need to provide in order to support such KPI reporting.
    
-
-
    Conventions
    
-
-
    Although this document is not an RFC, it will follow the conventions of rfc2119 in the use of the following terms:
    
-
-
      
-
    1. must - This word, or the terms “REQUIRED” or “SHALL”, mean that the definition is an absolute requirement for meeting best practice.
      2. 
-
    2. must not - This phrase, or the phrase “SHALL NOT”, mean that the definition is an absolute prohibition for meeting best practice.
      3. 
-
    3. should - This word, or the adjective “RECOMMENDED”, mean that there may exist valid reasons in particular circumstances to ignore a particular item, but the full implications must be understood and carefully weighed before choosing a different course.
      4. 
-
    4. should not - This phrase, or the phrase “NOT RECOMMENDED”, mean that there may exist valid reasons in particular circumstances when the particular behavior is acceptable or even useful, but the full implications should be understood and the case carefully weighed before implementing any behavior described with this label.
      5. 
-
    
-
-
    Summary
    
-
-
    In order to support basic agency and publisher KPIs:
    
-
-
      
-
    • Publishers must record funder information in their CrossRef deposits
      • 
-
    • Publishers must deposit the FundRef funder identifiers corresponding to their funder names where these exist in the FundRef Registry
      • 
-
    • Publishers should record award numbers when possible.
      • 
-
    • The Publisher should record funding information within CrossMark records if they are either implementing CrossMark or are planning to implement CrossMark within the next two years.
      • 
-
    • Publishers should record licensing information if they have it by means of a URI specifying the license under which the publication is made.
      • 
-
    • If publishers do not have licensing information, they should record a placeholder URI and fill in the target of the URI once they have agreed on licensing information.
      • 
-
    • Publishers should record full text links to the readable version(s) of the document. This may include different resources for the Version of Record (VOR) and Author Accepted Manuscript (AM).
      • 
-
    • Publishers should record full text links to representations of the document that are made available for TDM. These may be the same or different to the “readable” versions of the document pointed to above.
      • 
-
    • Where they are recording multiple versions of the document (e.g. AM & VOR), the publisher should map licensing information to the specific resource versions.
      • 
-
    • Publishers should record full text links to archived versions of the document identified by the CrossRef DOI.
      • 
-
    • Publishers should record archive arrangements made with third party archiving organizations where the document identified by the CrossRef DOI is archived with the third party.
      • 
-
    
-
-
    In order to enhance the utility of CrossRef metadata to agencies and in order to enable more sophisticated agency/publisher KPIs:
    
-
-
      
-
    • Publishers should consider participating in CrossMark in order to record updates, errata, corrigenda,retractions and withdrawals.
      • 
-
    • Publishers should consider depositing abstracts using CrossRef’s JATS abstract element support.
      • 
-
    • Publishers should consider collecting and depositing ORCIDs for publication authors.
      • 
-
    • Publishers should consider making the bibliographic metadata and references for documents resulting from agency funding maximally available by overriding CrossRef opt-outs using the <metadata_distribution_opt> and <reference_distribution_opt> elements.
      • 
-
    
-
-
    Funding information
    
-
-
    CrossRef supports the recording of funding information for a publication via its FundRef program. FundRef defines an open, standard registry of funder names and funder identifiers that can be used in order to increase the accuracy of the funding information recorded. Although FundRef supports recording award_numbers along with funder identifiers, FundRef does not define standards for recording award numbers as practice varies greatly across funders.
    
-
-
    To support funder KPIs, members must deposits funder metadata using the specifications defined for the FundRef program. Specifically, when depositing metadata you:
    
-
-
      
-
    1. must include funder information.
      2. 
-
    2. must not deposit your funder names without at least trying to map them to FundRef identifiers in the FundRef registry. Depositing funder names that are included in the FundRef registry, but without their respective FundRef Funder Identifiers, will pollute the FundRef metadata and lower the value of the service for all participants. Note that the KPI APIs will only work for Funder metadata that includes FundRef Funder Identifiers.
      3. 
-
    3. should include award numbers in FundRef metadata when possible. Although the standard KPI API does not make direct use of award numbers, individual agencies may be able to make use of included award numbers where found.
      4. 
-
    4. should deposit FundRef data as part of a CrossMark record if you (the publisher) already are (or are planning to become) a participant in CrossMark. There are two reasons for this: First, it ensures that the Funder Metadata is available both in a standard machine readable format AND via a standard UI for readers. Second, it ensures that the Funder metadata is made maximally reusable via a CC Zero license waiver. Note that publishers do not need to have implemented CrossMark yet to deposit Funder metadata via CrossMark. We expect that publishers may take a year or more before they have fully implemented all of CrossMark’s features.
      5. 
-
    
-
-
    See CrossRef’s Help pages for Technical details on depositing FundRef metadata. 
    
-
-
    License information
    
-
-
    One of the main drivers for the FunRef KPI API is that many funders are required to report on the public availability of the results and publications arising from funder-financed research. Funders are therefor interested in understanding how publications related to funded research are licensed. 
    
-
-
    To deposit license information, publishers must use the <license_ref> element. The value of the <license_ref> element must be a stable HTTP URI which points to a human-readable document that either includes (or guides the reader to) any copyright and/or licensing information related to the CrossRef DOI of the content. The URI must point either to a location on the publisher’s site or to the stable location of any well-known licenses such as those of the Creative Commons. 
    
-
-
    Note that it is entirely acceptable to record a <license_ref> URI as a “placeholder.” If you are still working out specific licensing terms, the URI you record should point to a blank page or even a simple re-assertion of the document’s copyright. There is a big difference between recording at least some <license_ref> URI and recording no <license_ref> URI at all. The former indicates an intent to eventually clarify licensing information, whereas the latter indicates that the licensing information is likely to remain ambiguous.
    
-
-
    Use of the <license_ref> element is best explained through examples.
    
-
-
    The <license_ref> for content licensed under the popular CC-BY license, would look like this:
    
-
-
    <license_ref>http://creativecommons.org/licenses/by/3.0/deed.en_US</license_ref>
-
    
-
-
    Where as the Journal of Psychoceramics might record that their content is licensed under a proprietary license like this:
    
-
-
    <license_ref>http://www.psychoceramics.org/license_v1.html</license_ref>
-
    
-
-
    You can deposit multiple <license_ref> elements- so the following would indicate that a document was available under a dual license (e.g. one for commercial applications and one for non-commercial applications).
    
-
-
    <license_ref>http://www.psychoceramics.org/non_commercial_license_v1.html</license_ref>
-<license_ref>http://www.psychoceramics.org/commercial_license_v1.html</license_ref>
-
    
-
-
    Embargos
    
-
-
    Publishers may want to record that a document is under embargo. In other words, that it is available under access control and a proprietary license for a set period of time, after which it is available under an open license. Publishers wishing to record embargoes should use the optional start_date attribute on the <license_ref> element.
    
-
-
    For example, the following records that the content is under a proprietary license from its date of publication on February 3, 2014 and that it is under a CC-BY license a year later on February 3, 2015:
    
-
-
    <license_ref start_date="2014-02-03">http://www.psychoceramics.org/license_v1.html</license_ref>
-<license_ref start_date="2015-02-03">http://creativecommons.org/licenses/by/3.0/deed.en_US</license_ref>
-
    
-
-
    Note that the value of the start_date element must be recorded using the format YYYY-MM-DD
-The start_date attribute can be combined with multiple <license_ref> elements to indicate that a document is under a proprietary license during an embargo, but that it is then under a dual (commercial/non-commercial) license a year later)
    
-
-
    <license_ref start_date="2014-02-03">http://www.psychoceramics.org/license_v1.html</license_ref>
-
-<license_ref start_date="2015-02-03">http://www.psychoceramics.org/non_commercial_license_v1.html</license_ref>
-
-<license_ref start_date="2015-02-03">http://www.psychoceramics.org/commercial_license_v1.html</license_ref>
-
    
-
-
    Note that there is no corresponding end_date attribute for the <license_ref> element. This is because including end dates could introduce ambiguities. For example:
    
-
-
      
-
    • Open Licenses, such as CC, do not have “end dates”.
      • 
-
    • With end dates, it would be possible to inadvertently record “gaps” between licenses.
      • 
-
    
-
-
    You might ask why one should record a license that starts in the future? Wouldn’t it be better to just update the <license_ref> element at the time the license changes? By recording that another license takes effect in the future, you are informing the consumer of the metadata that the current restricted license is only for the embargo period. In short, you are recording the intent to change the license when the embargo is done. Furthermore, providing additional metadata for a current publication at some future date is an additional chore for the publisher that might well be overlooked.
    
-
-
    In the above examples, the <license_ref> element is unqualified and should therefor be considered to apply to the content pointed to by any <resource> URIs included in the CrossRef metadata. The CrossRef metadata schema supports recording different license for different versions of the resource and this will be discussed below. However, first let’s look at at the role the <resource> element plays in providing funding agency KPIs.
    
-
-
    Recording links to full text and/or archived versions of documents, etc.
    
-
-
    Funders are not just interested in reporting on the licensing terms of publications resulting from funder-financed research. They are also interested in making sure that the full text content of the BAV is made available for reading, automated processing and archiving. 
    
-
-
    To this end, publishers need to be able to record links to the full text of the content to which a DOI refers. Additionally, publishers will want to offer different versions (e.g. AM or VOR) and different representations (e.g. PDF for viewing, XML for TDM, etc.) of the content tailored for specific applications.
    
-
-
    The <resource> element in CrossRef metadata is most often used to record an HTTP URI pointing at the publisher’s landing page for the publication identified by the CrossRef DOI in question. However, the CrossRef schema has long supported the recording of multiple <resource> elements in order to enable, for example:
    
-
-
      
-
    • Multiple resolution
      • 
-
    • Search engine indexing
      • 
-
    • CrossCheck indexing
      • 
-
    
-
-
    CrossRef has extended the ability to record multiple <resource> elements in order to allow the recording of URIs which point to the full text of content identified by the CrossRef DOI. The publisher can record multiple representations of the full text (e.g. PDF, XML, plain text) using the new mime_type attribute and then, through their access control systems, control who is able to reach which representation and under which conditions.
    
-
-
    Note that, by recording a <resource> that points to the full text, you are not necessarily guaranteeing that the URI will be accessible 
    
-
-
    Note also that the publisher could theoretically choose only to deposit <resource> elements for full text representations once an embargo has ended. However, this approach may prove fraught, as any mistakes or delays in the redeposit process might lead the funding agency to believe that the publisher has not made the relevant content accessible at the end of the embargo period.
    
-
-
    Further detail on using the <resource> element for recording links to full text can be found on the Prospect support site and in the CrossRef deposit schema documentation for the  <collection>  and  <resource>  elements.
    
-
-
    Different licenses for different versions of the content
    
-
-
    Some publishers may want to record different licenses for different versions of the <resource> element recorded in CrossRef metadata. For example, one <resource> element may point to a URI intended for subscribed readers, while another <resource> element may point to a version of the document intended for Text and Data Mining (TDM) applications. Similarly, a publisher may choose to apply one license to the “Author Accepted Manuscript” (AM) and another to the “Version of Record” (VOR).
    
-
-
    To accommodate these scenarios, the <license_ref> element supports an applies_to element. Similarly, the <resource> element has been extended to support a content_version attribute. Publishers can use these element/attribute combinations to apply specific licenses to specific versions of the resource. For example, to indicate the “VOR” version of a document is licensed under a proprietary license, but that the “AM” version of the same document is licensed under an open license, the <license_ref> and <resource> elements could be combined like this:
    
-
-
    <license_ref applies_to="vor">http://www.psychoceramics.org/license_v1.html</license_ref>
-
-<!-- … -->
-
-<license_ref applies_to="am">http://creativecommons.org/licenses/by/3.0/deed.en_US</license_ref>
-
-<!--- other CrossRef metadata -->
-
-<resource content_version="vor">http://www.psychoceramics.org/fulltext/vor/10.5555/12345678</resource>
-
-<!-- … -->
-
-<resource content_version="am">http://www.psychoceramics.org/fulltext/am/10.5555/12345678</resource>
-
    
-
-
    The <license_ref> and <resource> elements along with their respective start_date, applies_to, and content_type attributes can all be combined to support more complex assertions. So, for example the following example says that a document is only available under a proprietary license for readers during an embargo period, but is then available to the public for reading under a more open license and for non-commercial TDM applications under a specific TDM license:
    
-
-
    <license_ref start_date="2014-02-03" applies_to="vor">http://www.psychoceramics.org/license_v1.html</license_ref>
-
-<!-- … -->
-
-<license_ref start_date="2015-02-03" applies_to="am">http://www.psychoceramics.org/open_license.html</license_ref>
-
-<!-- … -->
-
-<license_ref start_date="2015-02-03" applies_to="tdm">http://www.psychoceramics.org/nc_tdm_license.html</license_ref>
-
-<!--- other CrossRef Metadata -->
-
-<resource content_version="vor">http://www.psychoceramics.org/fulltext/vor/10.5555/12345678</resource>
-
-<!-- … -->
-
-<resource content_version="am">http://www.psychoceramics.org/fulltext/am/10.5555/12345678</resource>
-
-<resource content_version="tdm">http://www.psychoceramics.org/fulltext/tdm/10.5555/12345678.xml</resource>
-
    
-
-
    Detailed information on recording licensing information in CrossRef metadata can be found in the CrossRef schema documentation for the  <license_ref>  element.
    
-
-
    “Libre” vs “Gratis”
    
-
-
    The license information recorded in the <licence_ref> element can tell you what you are allowed to do with the resources the licenses point to, but they do not say anything about whether or not there is a monetary charge involved.
-In order to allow a publisher to record whether access to the content requires payment, CrossRef supports a new <free-to-read/> element. The <free-to-read/> element is an empty element. It can include two attributes, a start_date and an end_date. The <free-to-read/> elements works as follows:
    
-
-
      
-
    • The presence of a  element in CrossRef metadata _should be interpreted to mean that the full text content pointed to by the DOI resource is available “gratis” during the time period specified by the start_date and end_date attributes.
      • 
-
    • If the  element only includes a start_date attribute, then the element should be interpreted to mean that the content pointed to by the DOI resource will be made gratis from start_date on.
      • 
-
    • If the  element only includes a end_date attribute, then the element should be interpreted to mean that the content pointed to by the DOI resource will be made gratis from the publication date to and including the end_date.
      • 
-
    • If the  element has no start_date or end_date attributes, then the element should be interpreted to mean that the content pointed to by the DOI resource is available “gratis” from the date of publication on.
      • 
-
    • If the  element is not present in the DOI record, one should not assume that the resource pointed at by the DOI is available to read “gratis”.
      • 
-
    
-
-
    When the <free-to-read> element is combined with the <license_ref> element, the publisher can record sophisticated information about the availability and reusability of content. For example:
    
-
-
    restrictive licenses and possibly a payment
    
-
-
    <license_ref>http://tinypublisher.org/licenses/proprietary.html</license_ref>
-
    
-
-
    restrictive licenses and no payment (e.g free copy of an article from a subscription journal)
    
-
-
    <free-to-read/>
-<!-- … -->
-<license_ref>http://tinypublisher.org/licenses/proprietary.html</license_ref>
-
    
-
-
    have unrestrictive licenses and a possibly a payment (e.g. a CC-BY licensed novel for sale on Amazon)
    
-
-
    <license_ref>http://creativecommons.org/licenses/by/3.0/deed.en_US</license_ref>
-
    
-
-
    have unrestricted licenses and NO payment
    
-
-
    <free-to-read/>
-<!-- … -->
-<license_ref>http://creativecommons.org/licenses/by/3.0/deed.en_US</license_ref>
-
    
-
-
    Recording third party archive arrangements
    
-
-
    Funders may be concerned that publisher links to full-text content will become unavailable in exceptional circumstances. They may stipulate that content is archived with a third party archiving organization, and may even suggest a list of acceptable archive organizations with which documents should be archived.
    
-
-
    Publishers can record the archive arrangement or archive intention of a document using the <archive_locations> element in CrossRef deposit metadata. Any number of archive locations can be specified, for example a document may be archived with both Portico and CLOCKSS:
    
-
-
    <archive_locations>
-  <archive name="CLOCKSS"/>
-  <archive name="Portico"/>
-</archive_locations>
-
    
-
-
    CrossRef maintains a vocabulary of archive locations within the CrossRef deposit schema. The latest list of possible archive location values can be found in the documentation for the  <archive> element .
    
-
-
    Bonus points
    
-
-
    The more metadata that publishers record for publications arising from agency funded research, the more useful that metadata will be to said agencies and the more value they will see from publishers. Where as the above sections details metadata elements that agencies will expect in order to be able to compile basic KPIs and offer portal services, additional metadata will allow agencies to create even more sophisticated KPIs and services. As such, publishers should seriously consider depositing the following additional metadata elements in their CrossRef deposits.
    
-
-
    Distributing standard bibliographic metadata
    
-
-
    Metadata deposited to CrossRef is made available freely via numerous CrossRef query APIs. However all deposited metadata is subject to opt-outs in the case of bulk distribution APIs and data dumps. In order to make sure that bibliographic metadata for publications arising from agency funding is maximally available, publishers should consider setting the value of the <metadata_distribution_opts> element for DOIs to any. Further details can be found in CrossRef’s schema documentation for the <metadata_distribution_opts> element.
    
-
-
    Distributing references
    
-
-
    References made in publications arising from agency funding can provide agencies with an overview of what literature is considered important in the fields that they fund. Many publishers deposit references to CrossRef as part of their participation CrossRef’s CitedBy service. However, participation in CitedBy does not automatically make references available via CrossRef’s standard APIs. In order for publishers to distribute references along with standard bibliographic metadata, publishers need to set the <reference_distribution_opt> element to any for each DOI deposit where they want to make references openly available. By setting this element, references for the DOI will be distributed without restriction through all of CrossRefs APIs and bulk metadata dumps. Further details can be found in CrossRef’s schema documentation for the <reference_distribution_opt> element.
    
-
-
    CrossMark
    
-
-
    CrossMark provides a standard mechanism for alerting researchers to updates to published documents- including corrections, errata, corrigenda retractions and withdrawals. Use of the CrossMark service sends a signal to researchers and agencies that publishers are committed to maintaining the integrity of the scholarly record. 
    
-
-
    Additionally, CrossMark also provides a standard, cross-publisher, user interface that researchers can use to view FundRef information and licensing information. This user interface works both from publisher landing pages and from published PDFs. More information can be found on the CrossMark support site
    
-
-
    Abstracts
    
-
-
    Many funding agencies are interested in building custom portals that highlight agency-funded research. In order to provide users of these portals with the best experience, agencies will want, where possible, to display abstracts of publications along with their standard bibliographic metadata.
    
-
-
    CrossRef supports the deposit of abstracts conforming to the JATS abstract element. Further details can be found in the CrossRef Schema Documentation of the <abstract> element.
    
-
-
    ORCIDs
    
-
-
    ORCIDs are unique identifiers for researchers. CrossRef supports the deposit of ORCIDs for authors. The presence of ORCIDs in CrossRef metadata will, in turn, allow agencies to tie agency funded research publications directly to researchers. Widespread use of ORCIDs in CrossRef deposits could even let agencies start to develop publication KPIs for researchers that they fund. Further details on CrossRef’s ORCID support can be found in the CrossRef Schema Documentation of the <ORCID> element
    
-
-
    Frequently Asked Questions
    
-
-
    Q: What license applies to the metadata retrieved by the CrossRef APIs to support key performance indicators (KPIs) for funding agencies?
-
    
-A: 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. 
    
-
-
    Q: What does it mean if a <license_ref> element has no start_date attribute?
-
    
-A: This should be interpreted to mean that the <license_ref> applies from the earliest publication date.
    
-
-
    Q: What does is mean if there is no applies_to attribute for the <license_ref> element?
-
    
-A: This should be interpreted to mean that the license_ref applies to all the <resource> elements in the record.
    
-
-
    Q: What does it mean if the <resource> element doesn’t have a content_version attribute?
-
    
-A: This should be interpreted to mean that any <resource> elements point to the version of record (‘vor’)
    
-
-
    Q: What does it mean if there is no correspondence between existing <license_ref> applies_to attributes and existing <resource> content_version attributes?
-
    
-A: This probably means the publisher made a mistake depositing the metadata. 
    
-
-
    XML Deposit Examples
    
-
-
    Full Deposits
    
-
-
    Full deposits use the standard deposit schema.
    
-
-
-
-
    Partial Deposits
    
-
-
    Partial deposits use the resource deposit schema.
    
-
-
    Partial deposits update only part of a DOI’s metadata. In the CrossRef help system
-they are referred to as resource deposits, but it is not just resources that can
-be provided as a partial deposit. Licenses, funding information and CrossMarks can also
-be provided as partial deposits.
    
-
-
    Many partial deposits can be provided in a single batch deposit. The <body> element can
-contain any number of partial deposits of any type, some of which may be partial deposits for
-the same DOI. For example, two partial deposits could be provided for the same DOI,
-one updating funding information, the other updating license information.
    
-
-
-
-
-
-
-    
    
-
-
\ No newline at end of file

From f2750710d4e71c8834d8052b948b8b33311a0638 Mon Sep 17 00:00:00 2001
From: Geoffrey Bilder 
Date: Fri, 28 Feb 2014 16:17:28 +0000
Subject: [PATCH 026/219] added koans

---
 rest_api_koans.md | 96 +++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 96 insertions(+)
 create mode 100644 rest_api_koans.md

diff --git a/rest_api_koans.md b/rest_api_koans.md
new file mode 100644
index 0000000..14be705
--- /dev/null
+++ b/rest_api_koans.md
@@ -0,0 +1,96 @@
+# CrossRef API Koans
+
+## How many DOI records does CrossRef have?
+
+    http://api.crossref.org/works?rows=0
+
+## How many journal article DOIs does CrossRef have?
+
+    http://api.crossref.org/types/journal-article/works?rows=0
+
+## How many report DOIs does CrossRef have?
+
+    http://api.crossref.org/types/journal-article/works?rows=0
+
+## How many works have license information?
+
+    http://api.crossref.org/works?filter=has-license:true&rows=0
+
+## Get first 25 works that have a license
+
+    http://api.crossref.org/works?filter=has-license:true&rows=25&offset=0
+
+## Get second 25 works that have a license
+
+    http://api.crossref.org/works?filter=has-license:true&rows=25&offset=25
+
+## How many license types are there? (FIXME)
+
+    http://api.crossref.org/licenses?rows=0
+    
+## Show first 25 licneses (FIXME)
+
+    http://api.crossref.org/licenses?rows=25&offset=0
+
+## How many works have a CC-BY license?
+
+    http://api.crossref.org/works?rows=0&filter=license.url:http://creativecommons.org/licenses/by/3.0/
+
+## See how many works have funder information (coming soon)
+
+    http://api.crossref.org/works?filter=has-funder:true&rows=0
+
+## How many member publishers CrossRef has
+
+    http://api.crossref.org/members?rows=0
+
+## First 25 members:
+
+    http://api.crossref.org/members?rows=25&offset=0
+
+## Second 25 members:
+
+    http://api.crossref.org/members?rows=25&offset=25
+
+## Overview of Hindawi's particpation in CrossRef
+
+    http://api.crossref.org/members?query=hindawi
+
+### same as:
+
+    http://api.crossref.org/members/98
+
+## Overview of Elsevier's particpation in CrossRef
+
+    http://api.crossref.org/members?query=elsevier
+
+### same as:
+
+    http://api.crossref.org/members/78
+
+## How many works does Elsevier have?
+
+    http://api.crossref.org/members/78/works?rows=0
+
+## First 25 Elsevier works
+
+    http://api.crossref.org/members/78/works?rows=25&offset=0
+
+## Second 25 Elsevier works
+
+    http://api.crossref.org/members/78/works?rows=25&offset=25
+
+## How many Elsevier works have license links?
+
+    http://api.crossref.org/members/78/works?filter=has-license:true&rows=0
+
+## How many Elseveir works have full text links
+
+    http://api.crossref.org/members/78/works?filter=has-full-text:true&rows=0
+
+
+
+
+
+
+

From 2ca61972a0d78da46e8f4b0b223c338e2bcbf7e5 Mon Sep 17 00:00:00 2001
From: Geoffrey Bilder 
Date: Fri, 28 Feb 2014 16:21:08 +0000
Subject: [PATCH 027/219] Update rest_api_koans.md

---
 rest_api_koans.md | 5 ++++-
 1 file changed, 4 insertions(+), 1 deletion(-)

diff --git a/rest_api_koans.md b/rest_api_koans.md
index 14be705..ed0995b 100644
--- a/rest_api_koans.md
+++ b/rest_api_koans.md
@@ -24,7 +24,7 @@
 
     http://api.crossref.org/works?filter=has-license:true&rows=25&offset=25
 
-## How many license types are there? (FIXME)
+## How many license types are there?
 
     http://api.crossref.org/licenses?rows=0
     
@@ -87,7 +87,10 @@
 ## How many Elseveir works have full text links
 
     http://api.crossref.org/members/78/works?filter=has-full-text:true&rows=0
+    
+## What license types does Elssvier support?
 
+    http://api.crossref.org/licenses?filter=member:78
 
 
 

From 61a02fe7a514fc957e23069b4af3d3cf0c7a25e1 Mon Sep 17 00:00:00 2001
From: Geoffrey Bilder 
Date: Fri, 28 Feb 2014 16:30:05 +0000
Subject: [PATCH 028/219] Update rest_api_koans.md

---
 rest_api_koans.md | 42 +++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 41 insertions(+), 1 deletion(-)

diff --git a/rest_api_koans.md b/rest_api_koans.md
index ed0995b..52a5d97 100644
--- a/rest_api_koans.md
+++ b/rest_api_koans.md
@@ -1,5 +1,14 @@
 # CrossRef API Koans
 
+## Version History
+
+- V1: 2014-02-26, first draft.
+- V2: 2014-02-28, added license examples
+
+## Overview
+
+The following short examples show how the CrossRef REST API can be used to issue sophisticated queries against the CrossRef system.
+
 ## How many DOI records does CrossRef have?
 
     http://api.crossref.org/works?rows=0
@@ -88,10 +97,41 @@
 
     http://api.crossref.org/members/78/works?filter=has-full-text:true&rows=0
     
-## What license types does Elssvier support?
+## What license types does Elsevier support?
 
     http://api.crossref.org/licenses?filter=member:78
 
+## Overview of Hindawi's particpation in CrossRef
+
+    http://api.crossref.org/members?query=hindawi
+
+### same as:
+
+    http://api.crossref.org/members/98
+    
+## How many works does Hindawi have?
+
+    http://api.crossref.org/members/98/works?rows=0
+
+## How many Hindawi works have license links?
+
+    http://api.crossref.org/members/98/works?filter=has-license:true&rows=0
+
+## How many Hindawi works have full text links
+
+    http://api.crossref.org/members/98/works?filter=has-full-text:true&rows=0
+    
+## What license types does Hindawi support?
+
+    http://api.crossref.org/licenses?filter=member:98
+    
+## What license type does the journal with a particular ISSN support
+
+    http://api.crossref.org/licenses?filter=issn:2090-8091
+
+## What licenses does a reasearcher with a particular ORCID publish under
+
+    http://api.crossref.org/licenses?filter=orcid:0000-0003-1340-5202
 
 
 

From d52cc22fe0c292c8e8a7cd3d2728c41cc074915b Mon Sep 17 00:00:00 2001
From: Geoffrey Bilder 
Date: Fri, 28 Feb 2014 16:36:58 +0000
Subject: [PATCH 029/219] Update rest_api_koans.md

---
 rest_api_koans.md | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/rest_api_koans.md b/rest_api_koans.md
index 52a5d97..b18d888 100644
--- a/rest_api_koans.md
+++ b/rest_api_koans.md
@@ -13,6 +13,10 @@ The following short examples show how the CrossRef REST API can be used to issue
 
     http://api.crossref.org/works?rows=0
 
+## What content types does CrossRef have?
+
+    http://api.crossref.org/types
+
 ## How many journal article DOIs does CrossRef have?
 
     http://api.crossref.org/types/journal-article/works?rows=0

From 07306072fed1165670334d8752e3501f9c3c0bf2 Mon Sep 17 00:00:00 2001
From: Geoffrey Bilder 
Date: Fri, 28 Feb 2014 16:48:36 +0000
Subject: [PATCH 030/219] Update rest_api_koans.md

---
 rest_api_koans.md | 50 +++++++++++++++++++++++++++++++++++++----------
 1 file changed, 40 insertions(+), 10 deletions(-)

diff --git a/rest_api_koans.md b/rest_api_koans.md
index b18d888..4f3d237 100644
--- a/rest_api_koans.md
+++ b/rest_api_koans.md
@@ -9,22 +9,54 @@
 
 The following short examples show how the CrossRef REST API can be used to issue sophisticated queries against the CrossRef system.
 
-## How many DOI records does CrossRef have?
+## Finding out what is in the CrossRef system
+
+You might start by wondering how much and what kinds of data exist in the CrossRef system.
+
+### How many DOI records does CrossRef have?
 
     http://api.crossref.org/works?rows=0
 
-## What content types does CrossRef have?
+### What content types does CrossRef have?
 
     http://api.crossref.org/types
 
-## How many journal article DOIs does CrossRef have?
+### How many journal article DOIs does CrossRef have?
 
     http://api.crossref.org/types/journal-article/works?rows=0
 
-## How many report DOIs does CrossRef have?
+### How many report DOIs does CrossRef have?
 
     http://api.crossref.org/types/journal-article/works?rows=0
 
+But eventually you will probably want to start looking at metadata records
+
+### Example 1
+
+### Example 2 
+
+And then you will want to start looking at metadata records that contain specific terms
+
+### Example 1
+
+    TDB
+   
+### Example 2
+
+    TBD
+
+So let's look at specific records
+
+### Example 1
+
+    TBD
+
+### Example 2
+
+    TBD
+
+Interesting. There is licnese information in there and full text links.
+
 ## How many works have license information?
 
     http://api.crossref.org/works?filter=has-license:true&rows=0
@@ -41,17 +73,15 @@ The following short examples show how the CrossRef REST API can be used to issue
 
     http://api.crossref.org/licenses?rows=0
     
-## Show first 25 licneses (FIXME)
-
-    http://api.crossref.org/licenses?rows=25&offset=0
-
 ## How many works have a CC-BY license?
 
     http://api.crossref.org/works?rows=0&filter=license.url:http://creativecommons.org/licenses/by/3.0/
 
-## See how many works have funder information (coming soon)
+## See how many works have funder information
 
     http://api.crossref.org/works?filter=has-funder:true&rows=0
+    
+It would be inetersting to drill-down and see specifics for CrossRef members
 
 ## How many member publishers CrossRef has
 
@@ -69,7 +99,7 @@ The following short examples show how the CrossRef REST API can be used to issue
 
     http://api.crossref.org/members?query=hindawi
 
-### same as:
+though once you have a member ID ('98', in this case), you should use that instead. So above is the same as:
 
     http://api.crossref.org/members/98
 

From 681093917d8389394e99cbb89c909c2c87d38c3b Mon Sep 17 00:00:00 2001
From: Geoffrey Bilder 
Date: Fri, 28 Feb 2014 16:49:47 +0000
Subject: [PATCH 031/219] Update rest_api_koans.md

---
 rest_api_koans.md | 8 ++++++--
 1 file changed, 6 insertions(+), 2 deletions(-)

diff --git a/rest_api_koans.md b/rest_api_koans.md
index 4f3d237..c349967 100644
--- a/rest_api_koans.md
+++ b/rest_api_koans.md
@@ -33,9 +33,13 @@ But eventually you will probably want to start looking at metadata records
 
 ### Example 1
 
-### Example 2 
+    TBD
+
+### Example 2
+
+    TBD
 
-And then you will want to start looking at metadata records that contain specific terms
+And then you will want to start looking for metadata records that contain specific terms
 
 ### Example 1
 

From 7135195db648b0ff9a2c7eb4cb3e50d92afdf8f5 Mon Sep 17 00:00:00 2001
From: Karl Jonathan Ward 
Date: Fri, 28 Feb 2014 22:37:52 +0000
Subject: [PATCH 032/219] Add funder count publisher breakdown examples

---
 rest_api_koans.md | 12 +++++++++++-
 1 file changed, 11 insertions(+), 1 deletion(-)

diff --git a/rest_api_koans.md b/rest_api_koans.md
index c349967..90cb25b 100644
--- a/rest_api_koans.md
+++ b/rest_api_koans.md
@@ -85,7 +85,17 @@ Interesting. There is licnese information in there and full text links.
 
     http://api.crossref.org/works?filter=has-funder:true&rows=0
     
-It would be inetersting to drill-down and see specifics for CrossRef members
+## See how many Hindawi works have funder information
+
+    http://api.crossref.org/members/98/works?filter=has-funder:true&rows=0
+    
+  or
+    
+    http://api.crossref.org/works?filter=member:98,has-funder:true&rows=0
+    
+## See how many Elsevier works have funder information
+
+    http://api.crossref.org/member/78/works?filter=has-funder:true&rows=0
 
 ## How many member publishers CrossRef has
 

From 384284243621bd6ee64687d0ccd8433c4d89cfd7 Mon Sep 17 00:00:00 2001
From: Karl Jonathan Ward 
Date: Mon, 10 Mar 2014 20:06:21 +0000
Subject: [PATCH 033/219] Bits of deposit API docs

---
 deposit_api.md | 83 ++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 83 insertions(+)
 create mode 100644 deposit_api.md

diff --git a/deposit_api.md b/deposit_api.md
new file mode 100644
index 0000000..4987833
--- /dev/null
+++ b/deposit_api.md
@@ -0,0 +1,83 @@
+# CrossRef RESTful Deposit API
+
+## Versioning
+
+| Date | Version | Changes |
+|------|---------|---------|
+| 2014-03-10 | v1 | Initial version |
+
+## Background
+
+CrossRef provides two deposit mechanisms for our members and manuscript system vendors.
+The first is an API that can accept automated deposits of CrossRef metadata. This API
+has some deficiencies, including an inability to programatically track the status of
+a deposit, and an outdated system for
+
+This API attempts to address deficiencies within the current CrossRef XML deposit API.
+
+## Extension to the CrossRef REST API
+
+This document provides an extension to the CrossRef REST API, described
+[here](http://github.com/CrossRef/rest-api-doc/funder_api_doc.md). It uses the same
+API versioning scheme, JSON response format and concepts of singular and listy
+responses. The base URI for this API is:
+
+    http://api.crossref.org
+
+However, the routes described in this documentation must be accessed over HTTPS:
+
+    https://api.crossref.org
+
+## Authentication
+
+All routes described in this document require authentication using CrossRef member
+credentials. These must be supplied on each requests using the HTTP basic authentication
+scheme. Member credentials are provided in a HTTP header as described in
+[RFC2617](https://www.ietf.org/rfc/rfc2617.txt).
+
+## Making a Deposit
+
+    POST /deposits
+
+Requests to `/deposits` must be authenticated and made over HTTPS.
+
+Deposits are made by POSTing the contents of a deposit to `/deposits`. If initial
+checks against the deposit (for example, XML validation) succeed, a `303` redirect
+will be returned with a `Location` header defining the deposit status query link:
+
+    HTTP/1.1 303 See Other
+	Location: /deposits/1234-5678-1234-5678
+
+### Specifying a Deposit Content Type
+
+Deposits POSTed to `/deposits` _must_ specify a deposit content type. This is done
+by setting a `Content-Type` header in requests to `/deposits`. It _must_ be set to
+one of:
+
+| Content Type | Description |
+|--------------|-------------|
+| application/vnd.crossref.deposit+xml | [Full deposit](http://doi.crossref.org/schemas/crossref4.3.4.xsd) |
+| application/vnd.crossref.partial+xml | [Partial (resource) deposit](http://doi.crossref.org/schemas/doi_resources4.3.2.xsd) |
+
+### Specifying a Ping Back URL
+
+    POST /deposits?pingback={url_encoded_url}
+
+## Querying the Status of a Deposit
+
+    GET /deposits/{id}
+
+Requests to `/deposits/{id}` must be authenticated and made over HTTPS.
+
+Retrieve the status of a deposit, including submission status and details of any
+errors by making a GET request to the redirect URL returned when making a deposit.
+
+## Retrieving Original Deposit Objects
+
+    GET /deposits/{id}/data
+
+Requests to `/deposits/{id}/data` must be authenticated and made over HTTPS.
+
+
+
+

From 3d3d51ee030a4afe993fb8cf20b0f2d5d1d2e4a9 Mon Sep 17 00:00:00 2001
From: Karl Jonathan Ward 
Date: Mon, 10 Mar 2014 20:19:29 +0000
Subject: [PATCH 034/219] GET /deposits - list previous deposits

---
 deposit_api.md | 12 ++++++++++++
 1 file changed, 12 insertions(+)

diff --git a/deposit_api.md b/deposit_api.md
index 4987833..db362c1 100644
--- a/deposit_api.md
+++ b/deposit_api.md
@@ -63,6 +63,18 @@ one of:
 
     POST /deposits?pingback={url_encoded_url}
 
+The deposit API can return information on completed or failed deposits to a user by making
+a HTTP request to a per-deposit defined URL. Use the `pingback` parameter to specify
+a URL encoded ping back URL. The user must specify a URL that will return
+a `200` HTTP status response on successfully accepting ping back information. If the deposit
+API receives any other HTTP status, or if the URL is unaccessible for any reason, the API will
+make repeated requests to the URL, following a pattern of exponential back off. The maximum number
+of request attempts the API will make is undefined.
+
+## Listing Previous Deposits
+
+    GET /deposits
+
 ## Querying the Status of a Deposit
 
     GET /deposits/{id}

From 50ba9129afbbd5a8bb10ab0335f482fe6882ac49 Mon Sep 17 00:00:00 2001
From: Karl Jonathan Ward 
Date: Mon, 10 Mar 2014 21:54:04 +0000
Subject: [PATCH 035/219] More text in deposit_api.md

---
 deposit_api.md | 32 +++++++++++++++++++++++---------
 1 file changed, 23 insertions(+), 9 deletions(-)

diff --git a/deposit_api.md b/deposit_api.md
index db362c1..c156448 100644
--- a/deposit_api.md
+++ b/deposit_api.md
@@ -33,7 +33,13 @@ However, the routes described in this documentation must be accessed over HTTPS:
 All routes described in this document require authentication using CrossRef member
 credentials. These must be supplied on each requests using the HTTP basic authentication
 scheme. Member credentials are provided in a HTTP header as described in
-[RFC2617](https://www.ietf.org/rfc/rfc2617.txt).
+[RFC2617](https://www.ietf.org/rfc/rfc2617.txt). To create an `Authorization` header:
+
+1. Create a string, "username:password"
+2. Base64 encode the username, password string
+3. Insert this bas64 string into an `Authorization` header:
+
+        Authorization: Basic {base64 encoded user:password pair}
 
 ## Making a Deposit
 
@@ -63,18 +69,24 @@ one of:
 
     POST /deposits?pingback={url_encoded_url}
 
-The deposit API can return information on completed or failed deposits to a user by making
-a HTTP request to a per-deposit defined URL. Use the `pingback` parameter to specify
-a URL encoded ping back URL. The user must specify a URL that will return
-a `200` HTTP status response on successfully accepting ping back information. If the deposit
-API receives any other HTTP status, or if the URL is unaccessible for any reason, the API will
-make repeated requests to the URL, following a pattern of exponential back off. The maximum number
-of request attempts the API will make is undefined.
+The deposit API can return information on completed or failed deposits to a
+user by making a HTTP request to a per-deposit defined URL. Use the `pingback`
+parameter to specify a URL encoded ping back URL. The user must specify a URL
+that will return a `200` HTTP status response on successfully accepting ping
+back information. If the deposit API receives any other HTTP status, or if the
+URL is unaccessible for any reason, the API will make repeated requests to the
+URL, following a pattern of exponential back off. The maximum number of request
+attempts the API will make is undefined.
 
 ## Listing Previous Deposits
 
     GET /deposits
 
+Requests to `/deposits` must be authenticated and made over HTTPS.
+
+List previous deposists. The list of deposits can be paged with the `rows` and
+`offset` query parameters (see the [CrossRef REST API documentation]()).
+
 ## Querying the Status of a Deposit
 
     GET /deposits/{id}
@@ -90,6 +102,8 @@ errors by making a GET request to the redirect URL returned when making a deposi
 
 Requests to `/deposits/{id}/data` must be authenticated and made over HTTPS.
 
-
+The original deposit XML may be retrieved using the `/deposits/{id}/data` route.
+The response `Content-Type` will match the content type specified when depositing
+the XML.
 
 

From e0cf0cc373f1f5df04299f6a300f3874fa5124bf Mon Sep 17 00:00:00 2001
From: Karl Jonathan Ward 
Date: Mon, 10 Mar 2014 21:59:29 +0000
Subject: [PATCH 036/219] Add missing links

---
 deposit_api.md | 19 +++++++++++++------
 1 file changed, 13 insertions(+), 6 deletions(-)

diff --git a/deposit_api.md b/deposit_api.md
index c156448..0dd0bc0 100644
--- a/deposit_api.md
+++ b/deposit_api.md
@@ -8,12 +8,18 @@
 
 ## Background
 
-CrossRef provides two deposit mechanisms for our members and manuscript system vendors.
-The first is an API that can accept automated deposits of CrossRef metadata. This API
-has some deficiencies, including an inability to programatically track the status of
-a deposit, and an outdated system for
+CrossRef provides a deposit mechanisms for our members and manuscript system vendors.
+The current deposit mechanism provides a URL end-point that can accept deposits of
+CrossRef metadata. However, this mechanisn has some deficiencies, including:
 
-This API attempts to address deficiencies within the current CrossRef XML deposit API.
+- an inability to programatically track the status of a deposit
+- an outdated method of returning deposit results to a user (e-mail responses containing
+  success or failure notices)
+- no way of programatically querying for a historic list of deposits
+- no way of programatically retrieveing previously deposited XML.
+
+This docuemnt proposes a RESTful deposit API that attempts to address deficiencies
+within the current CrossRef XML deposit mechanism.
 
 ## Extension to the CrossRef REST API
 
@@ -85,7 +91,8 @@ attempts the API will make is undefined.
 Requests to `/deposits` must be authenticated and made over HTTPS.
 
 List previous deposists. The list of deposits can be paged with the `rows` and
-`offset` query parameters (see the [CrossRef REST API documentation]()).
+`offset` query parameters (see the
+[CrossRef REST API documentation](https://github.com/CrossRef/rest-api-doc/blob/master/funder_kpi_api.md)).
 
 ## Querying the Status of a Deposit
 

From 948b694e73645e7f43588803a1628e9c3dd57ad8 Mon Sep 17 00:00:00 2001
From: Karl Jonathan Ward 
Date: Mon, 10 Mar 2014 22:58:36 +0000
Subject: [PATCH 037/219] Specify some filters for /deposits.

---
 deposit_api.md    | 15 ++++++++++++++-
 funder_kpi_api.md |  4 +---
 2 files changed, 15 insertions(+), 4 deletions(-)

diff --git a/deposit_api.md b/deposit_api.md
index 0dd0bc0..a26d259 100644
--- a/deposit_api.md
+++ b/deposit_api.md
@@ -34,7 +34,7 @@ However, the routes described in this documentation must be accessed over HTTPS:
 
     https://api.crossref.org
 
-## Authentication
+## Authorization
 
 All routes described in this document require authentication using CrossRef member
 credentials. These must be supplied on each requests using the HTTP basic authentication
@@ -94,6 +94,19 @@ List previous deposists. The list of deposits can be paged with the `rows` and
 `offset` query parameters (see the
 [CrossRef REST API documentation](https://github.com/CrossRef/rest-api-doc/blob/master/funder_kpi_api.md)).
 
+The `/deposits` route also specifies some filters:
+
+| Filter | Possible Values | Description |
+|--------|-----------------|-------------|
+| status | One of `submitted`, `failed` or `completed` | Return only those deposits with given status |
+| from-submitted-date | Date | Return only those deposits that were deposited on or after the given date |
+| until-submitted-date | Date | Return only those deposits that were deposited on or before the given date |
+
+Dates should be of the form `YYYY-MM-DD`, `YYYY-MM` or `YYYY`.
+
+For more information on filters, including how to specify them, see the filters section
+in the [CrossRef REST API documentation](https://github.com/CrossRef/rest-api-doc/blob/master/funder_kpi_api.md).
+
 ## Querying the Status of a Deposit
 
     GET /deposits/{id}
diff --git a/funder_kpi_api.md b/funder_kpi_api.md
index d196b43..f59dfa0 100644
--- a/funder_kpi_api.md
+++ b/funder_kpi_api.md
@@ -178,8 +178,6 @@ Queries support a subset of [DisMax](https://wiki.apache.org/solr/DisMax), so, f
 or using JSON
 
     curl -X GET -H "Content-Type: application/json" -d '{"query": "renear -ontologies"}'  http://api.crossref.org/works
-    
-
 
 ## Filter Names
 
@@ -228,7 +226,7 @@ CrossRef also has member IDs for depositing organisations. A single member may c
 
 ### Notes on dates
 
-Note that dates in filters should always be of the form `YYYY-MM-DD`. Also not 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 not 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
 

From f546427af283125f3410302b16776425f427f99a Mon Sep 17 00:00:00 2001
From: Karl Jonathan Ward 
Date: Thu, 20 Mar 2014 11:51:53 +0000
Subject: [PATCH 038/219] Document error types

---
 deposit_api.md | 34 +++++++++++++++++++++++++++++++++-
 1 file changed, 33 insertions(+), 1 deletion(-)

diff --git a/deposit_api.md b/deposit_api.md
index a26d259..1883273 100644
--- a/deposit_api.md
+++ b/deposit_api.md
@@ -107,6 +107,10 @@ Dates should be of the form `YYYY-MM-DD`, `YYYY-MM` or `YYYY`.
 For more information on filters, including how to specify them, see the filters section
 in the [CrossRef REST API documentation](https://github.com/CrossRef/rest-api-doc/blob/master/funder_kpi_api.md).
 
+## Listing Previously Deposited DOIs
+
+    GET /deposits/dois
+
 ## Querying the Status of a Deposit
 
     GET /deposits/{id}
@@ -116,6 +120,35 @@ Requests to `/deposits/{id}` must be authenticated and made over HTTPS.
 Retrieve the status of a deposit, including submission status and details of any
 errors by making a GET request to the redirect URL returned when making a deposit.
 
+### Error Types
+
+| Major Type | Minor Type |
+|------------|------------|
+| submission | added-with-conflict |
+|            | version-older-than-last |
+|            | title-deleted-by-crossref-admin |
+|            | npe |
+|            | unique-doi |
+| permission | not-your-handle |
+|            | not-your-prefix |
+|            | not-your-title |
+|            | not-your-issn |
+| xml-syntax | malformed |
+|            | schema-validation-fail |
+|            | bad-character-data |
+|            | content-in-prolog |
+|            | bad-character-encoding |
+| xml-content | differing-prefixes |
+|             | invalid-year |
+|             | submission-version-is-null |
+
+## Querying the Deposit Status of a DOI
+
+    GET /deposits/dois/{url_encoded_doi}
+
+Get the deposit history of a DOI. Lists all successful or outstanding deposits
+for a DOI. Also provides a summary indicating whether or not 
+
 ## Retrieving Original Deposit Objects
 
     GET /deposits/{id}/data
@@ -126,4 +159,3 @@ The original deposit XML may be retrieved using the `/deposits/{id}/data` route.
 The response `Content-Type` will match the content type specified when depositing
 the XML.
 
-

From 1b20089caeaa7848308ac1b6bd514242a872de97 Mon Sep 17 00:00:00 2001
From: Joe Wass 
Date: Thu, 20 Mar 2014 11:59:58 +0000
Subject: [PATCH 039/219] Typos

---
 deposit_api.md | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/deposit_api.md b/deposit_api.md
index 1883273..881f8c0 100644
--- a/deposit_api.md
+++ b/deposit_api.md
@@ -10,7 +10,7 @@
 
 CrossRef provides a deposit mechanisms for our members and manuscript system vendors.
 The current deposit mechanism provides a URL end-point that can accept deposits of
-CrossRef metadata. However, this mechanisn has some deficiencies, including:
+CrossRef metadata. However, this mechanism has some deficiencies, including:
 
 - an inability to programatically track the status of a deposit
 - an outdated method of returning deposit results to a user (e-mail responses containing
@@ -18,7 +18,7 @@ CrossRef metadata. However, this mechanisn has some deficiencies, including:
 - no way of programatically querying for a historic list of deposits
 - no way of programatically retrieveing previously deposited XML.
 
-This docuemnt proposes a RESTful deposit API that attempts to address deficiencies
+This document proposes a RESTful deposit API that attempts to address deficiencies
 within the current CrossRef XML deposit mechanism.
 
 ## Extension to the CrossRef REST API
@@ -58,7 +58,7 @@ checks against the deposit (for example, XML validation) succeed, a `303` redire
 will be returned with a `Location` header defining the deposit status query link:
 
     HTTP/1.1 303 See Other
-	Location: /deposits/1234-5678-1234-5678
+    Location: /deposits/1234-5678-1234-5678
 
 ### Specifying a Deposit Content Type
 

From 575fadfc278e298763eb2326e8d576a59e43f30f Mon Sep 17 00:00:00 2001
From: Karl Jonathan Ward 
Date: Thu, 20 Mar 2014 13:45:49 +0000
Subject: [PATCH 040/219] Fix link to REST api

---
 deposit_api.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/deposit_api.md b/deposit_api.md
index 881f8c0..3bc9bbe 100644
--- a/deposit_api.md
+++ b/deposit_api.md
@@ -24,7 +24,7 @@ within the current CrossRef XML deposit mechanism.
 ## Extension to the CrossRef REST API
 
 This document provides an extension to the CrossRef REST API, described
-[here](http://github.com/CrossRef/rest-api-doc/funder_api_doc.md). It uses the same
+[here](http://github.com/CrossRef/rest-api-doc/funder_kpi_api.md). It uses the same
 API versioning scheme, JSON response format and concepts of singular and listy
 responses. The base URI for this API is:
 

From caf55eb5395827f742be9c98c70f204ee9700096 Mon Sep 17 00:00:00 2001
From: Karl Jonathan Ward 
Date: Wed, 2 Apr 2014 11:22:42 +0100
Subject: [PATCH 041/219] cURL deposit example

---
 deposit_api.md | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/deposit_api.md b/deposit_api.md
index 3bc9bbe..be6ac0d 100644
--- a/deposit_api.md
+++ b/deposit_api.md
@@ -60,6 +60,10 @@ will be returned with a `Location` header defining the deposit status query link
     HTTP/1.1 303 See Other
     Location: /deposits/1234-5678-1234-5678
 
+Making a deposit with cURL:
+
+    $ curl -i -H "Content-Type: application/vnd.crossref.deposit+xml" -u username:password --data-binary @my-deposit.xml https://api.crossref.org/deposits
+
 ### Specifying a Deposit Content Type
 
 Deposits POSTed to `/deposits` _must_ specify a deposit content type. This is done

From 53cd9e247d6a6a0903128af34609744ec4842445 Mon Sep 17 00:00:00 2001
From: Karl Jonathan Ward 
Date: Wed, 2 Apr 2014 14:38:40 +0100
Subject: [PATCH 042/219] Mention doi filter for /deposits route

---
 deposit_api.md | 14 +++++++-------
 1 file changed, 7 insertions(+), 7 deletions(-)

diff --git a/deposit_api.md b/deposit_api.md
index be6ac0d..1cd9698 100644
--- a/deposit_api.md
+++ b/deposit_api.md
@@ -105,16 +105,13 @@ The `/deposits` route also specifies some filters:
 | status | One of `submitted`, `failed` or `completed` | Return only those deposits with given status |
 | from-submitted-date | Date | Return only those deposits that were deposited on or after the given date |
 | until-submitted-date | Date | Return only those deposits that were deposited on or before the given date |
+| doi | DOI | Return only those deposits that deposited against the given DOI |
 
 Dates should be of the form `YYYY-MM-DD`, `YYYY-MM` or `YYYY`.
 
 For more information on filters, including how to specify them, see the filters section
 in the [CrossRef REST API documentation](https://github.com/CrossRef/rest-api-doc/blob/master/funder_kpi_api.md).
 
-## Listing Previously Deposited DOIs
-
-    GET /deposits/dois
-
 ## Querying the Status of a Deposit
 
     GET /deposits/{id}
@@ -148,10 +145,13 @@ errors by making a GET request to the redirect URL returned when making a deposi
 
 ## Querying the Deposit Status of a DOI
 
-    GET /deposits/dois/{url_encoded_doi}
+    GET /deposits?filter=doi:{url_encoded_doi}
+
+Get the deposit history of a DOI. Lists all deposits for a DOI. Useful to combile with
+other filters, such as status. For example, check if a given DOI has had a successful
+deposit. If it has, those deposits will be returned, if not, no results will return:
 
-Get the deposit history of a DOI. Lists all successful or outstanding deposits
-for a DOI. Also provides a summary indicating whether or not 
+    GET /deposits?filter=doi:{url_encoded_doi},status:completed
 
 ## Retrieving Original Deposit Objects
 

From 26ba6f5fce489661f9617c3e2b94b026b7b9f736 Mon Sep 17 00:00:00 2001
From: Karl Jonathan Ward 
Date: Wed, 2 Apr 2014 15:24:28 +0100
Subject: [PATCH 043/219] How to deposit a test deposit

---
 deposit_api.md | 9 +++++++++
 1 file changed, 9 insertions(+)

diff --git a/deposit_api.md b/deposit_api.md
index 1cd9698..9195035 100644
--- a/deposit_api.md
+++ b/deposit_api.md
@@ -88,6 +88,14 @@ URL is unaccessible for any reason, the API will make repeated requests to the
 URL, following a pattern of exponential back off. The maximum number of request
 attempts the API will make is undefined.
 
+### Depositing a Test Deposit
+
+    POST /deposits?test=true
+
+Set the `test` paramter to `true`, `t` or `1` (any other value is considered false)
+to make a test deposit. Such a deposit will go through the normal deposit process
+but its contents will not be made live. By default, `test` is false.
+
 ## Listing Previous Deposits
 
     GET /deposits
@@ -106,6 +114,7 @@ The `/deposits` route also specifies some filters:
 | from-submitted-date | Date | Return only those deposits that were deposited on or after the given date |
 | until-submitted-date | Date | Return only those deposits that were deposited on or before the given date |
 | doi | DOI | Return only those deposits that deposited against the given DOI |
+| test | One of `true`, `t`, `1`, `false`, `f`, `0` | Return only those deposits that are or are not test deposits. By default all deposits, both test and live, are returned. |
 
 Dates should be of the form `YYYY-MM-DD`, `YYYY-MM` or `YYYY`.
 

From 9abf19db8423fca15907242962ce06c2fa243c98 Mon Sep 17 00:00:00 2001
From: Karl Jonathan Ward 
Date: Wed, 2 Apr 2014 15:26:34 +0100
Subject: [PATCH 044/219] Mention deposit type filter

---
 deposit_api.md | 1 +
 1 file changed, 1 insertion(+)

diff --git a/deposit_api.md b/deposit_api.md
index 9195035..d7afb3b 100644
--- a/deposit_api.md
+++ b/deposit_api.md
@@ -115,6 +115,7 @@ The `/deposits` route also specifies some filters:
 | until-submitted-date | Date | Return only those deposits that were deposited on or before the given date |
 | doi | DOI | Return only those deposits that deposited against the given DOI |
 | test | One of `true`, `t`, `1`, `false`, `f`, `0` | Return only those deposits that are or are not test deposits. By default all deposits, both test and live, are returned. |
+| type| Content Type | Return only those deposits with the given content type (mime type) |
 
 Dates should be of the form `YYYY-MM-DD`, `YYYY-MM` or `YYYY`.
 

From e3f04c8b1467686e82f76b253d2d2eb0212f6e98 Mon Sep 17 00:00:00 2001
From: Karl Jonathan Ward 
Date: Mon, 7 Apr 2014 21:00:57 +0100
Subject: [PATCH 045/219] Document deposit xml changes

---
 deposit_api.md | 13 +++++++++++++
 1 file changed, 13 insertions(+)

diff --git a/deposit_api.md b/deposit_api.md
index d7afb3b..c4ed1d7 100644
--- a/deposit_api.md
+++ b/deposit_api.md
@@ -64,6 +64,19 @@ Making a deposit with cURL:
 
     $ curl -i -H "Content-Type: application/vnd.crossref.deposit+xml" -u username:password --data-binary @my-deposit.xml https://api.crossref.org/deposits
 
+Deposits are modified slightly from the submitted form. This is to faciliate
+some of the features of this API. Deposit e-mail addresses are changed to an
+e-mail address where deposit notifications can be intercepted by this API.
+Deposit `batch ID`s are changed to match the deposit ID given out by the API.
+
+Deposits may be made where the e-mail and `batch ID` are left blank. However, the
+elements themselves must be present to pass schema validation.
+
+| XPath | Content change |
+|-------|----------------|
+| //head/doi_batch_id | Changed to match deposit resource ID (as in `/deposits/{ID}`) |
+| //head/email_address | Changed to `labs-notifications@crossref.org` |
+
 ### Specifying a Deposit Content Type
 
 Deposits POSTed to `/deposits` _must_ specify a deposit content type. This is done

From 619cd485a6b3bceba8ab27a72ad7a94503a461ad Mon Sep 17 00:00:00 2001
From: Geoffrey Bilder 
Date: Wed, 23 Apr 2014 10:03:39 +0100
Subject: [PATCH 046/219] added first draft of API tour

---
 rest_api_tour.md | 161 +++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 161 insertions(+)
 create mode 100644 rest_api_tour.md

diff --git a/rest_api_tour.md b/rest_api_tour.md
new file mode 100644
index 0000000..6ce79c3
--- /dev/null
+++ b/rest_api_tour.md
@@ -0,0 +1,161 @@
+# CrossRef TDM API Tour
+
+## Version History
+
+- V1: 2014-04-18, first draft.
+
+## Overview
+
+The following short examples show how the CrossRef REST APIs can be used to provide CrossPublisher suport for TDM applications. This demonstration is a bit of a paradox- it is targeted at a  non-technical audience who wants to understand a little but about the technical infrastructure that researchers can leverage for TDM applications.
+
+## Technical notes
+
+In many cases, you can simply paste the example URIs into a browser's URL box, but if you want to see the resulting JSON formatted correctly, then we recommend that you install one of the following plugins:
+
+- Firefox Users:
+- Chrome Users:
+
+Some of the demonstrations here require the use of content negotiation. This is difficult to demonstrate in a browser unless you use a special plugin. Accordingly, the URIs for this demo have also been included as a project for the XXXX plugin available for Chrome.
+
+## A fake problem
+
+A researcher is interested in text mining all a set of literature mentioning the word "blood"
+
+## Identifying a Corpus
+
+Once a researcher has identified a problem, they need to identify the corpus that they want to explore using TDM. This corpus might be small (a few hundred items) or it might be large (millions of items). But in either case, it is likely that the corpus will span multiple publishers in multiple countries and with multiple business models.
+
+CrossRef is not a discovery service. We expect that many third parties, both for profit and non-profit, will provide researchers with the discovery tools needed in order to identify a the Corpus of literature that they wish to mine for their particular application. As long as these third-party services allow the researcher to easily download the DOIs of the content they wish to mine, then
+
+Having said that, CrossRef does provide some primitive metadata-based discovery tools which we will use to demonstrate a process for identifying a Corpus.
+
+## Finding out what is in the CrossRef system
+
+How many members does CrossRef have?
+
+    http://api.crossref.org/members?rows=0
+
+Who are they? Let's look at first 100 members
+
+    http://api.crossref.org/members?rows=100
+
+And the second 100 members
+
+    http://api.crossref.org/members?rows=100&offset=100
+
+How many DOI records does CrossRef have?
+
+    http://api.crossref.org/works?rows=0
+
+What content types does CrossRef have?
+
+    http://api.crossref.org/types
+
+How many journal article DOIs does CrossRef have?
+
+    http://api.crossref.org/types/journal-article/works?rows=0
+
+How many proceedings articles DOIs does CrossRef have?
+
+    http://api.crossref.org/types/proceedings-article/works?rows=0
+
+But eventually you will probably want to start looking at metadata records. Lets search for records that have the word "blood" in the metadata and see how many there are.
+
+    http://api.crossref.org/works?query=%22blood%22&rows=0
+
+Lets look at some of the results.
+
+    http://api.crossref.org/works?query=%22blood%22&
+
+Now lets look at one of the records
+
+    http://api.crossref.org/works/10.1155/2014/413629
+
+Interesting. The record has ORCIDs, fulltext links, and license links. You need license and fulltext links to text and data mine the content.
+
+How many works have license information?
+
+    http://api.crossref.org/works?filter=has-license:true&rows=0
+
+How many license types are there?
+
+    http://api.crossref.org/licenses?rows=0
+
+How many works have a CC-BY license?
+
+    http://api.crossref.org/works?rows=0&filter=license.url:http://creativecommons.org/licenses/by/3.0/
+
+
+Ok, lets see how many records with the word "blood" in the metadata have license information and full text links
+
+    http://api.crossref.org/works?filter=has-license:true,has-full-text:true&query=blood&rows=0
+
+Let's download the results and download the content locally to TDM
+
+    http://api.crossref.org/works?filter=has-license:true,has-full-text:true&query=blood&rows=0
+
+
+
+## Other examples
+
+See how many works have funder information
+
+    http://api.crossref.org/works?filter=has-funder:true&rows=0
+
+See how many Hindawi works have funder information
+
+    http://api.crossref.org/members/98/works?filter=has-funder:true&rows=0
+
+  or
+
+    http://api.crossref.org/works?filter=member:98,has-funder:true&rows=0
+
+See how many Elsevier works have funder information
+
+    http://api.crossref.org/works?filter=member:78,has-funder:true&rows=0
+
+
+Overview of Hindawi's particpation in CrossRef
+
+    http://api.crossref.org/members?query=hindawi
+
+
+Overview of Elsevier's particpation in CrossRef
+
+    http://api.crossref.org/members?query=elsevier
+
+How many works does Elsevier have?
+
+    http://api.crossref.org/members/78/works?rows=0
+
+First 25 Elsevier works
+
+    http://api.crossref.org/members/78/works?rows=25&offset=0
+
+Second 25 Elsevier works
+
+    http://api.crossref.org/members/78/works?rows=25&offset=25
+
+How many Elsevier works have license links?
+
+    http://api.crossref.org/members/78/works?filter=has-license:true&rows=0
+
+How many Elsevier works have full text links
+
+    http://api.crossref.org/members/78/works?filter=has-full-text:true&rows=0
+
+What license types does Elsevier support?
+
+    http://api.crossref.org/licenses?filter=member:78
+
+What license types does Hindawi support?
+
+    http://api.crossref.org/licenses?filter=member:98
+
+What license type does the journal with a particular ISSN support
+
+    http://api.crossref.org/licenses?filter=issn:2090-8091
+
+What licenses does a reasearcher with a particular ORCID publish under
+
+    http://api.crossref.org/licenses?filter=orcid:0000-0003-1340-5202

From 3517cadc06b56698fdade360314703a4436a2d7d Mon Sep 17 00:00:00 2001
From: cmurphyUSAID 
Date: Wed, 23 Apr 2014 11:36:34 -0400
Subject: [PATCH 047/219] Update funder_kpi_api.md

---
 funder_kpi_api.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/funder_kpi_api.md b/funder_kpi_api.md
index f59dfa0..431b722 100644
--- a/funder_kpi_api.md
+++ b/funder_kpi_api.md
@@ -90,7 +90,7 @@ Note that the "message-type" returned will differ from the mime-type:
 - member-list (list)
 
 
-Normally, and API list result will return both the summary and the items. If you want to just retrieve the summary, you can do so by specifying that the number of rows returned should be zero. 
+Normally, an API list result will return both the summary and the items. If you want to just retrieve the summary, you can do so by specifying that the number of rows returned should be zero. 
 ### Sort order
 
 If the API call includes a query, then the sort order will be by the relevance score. If no query is included, then the sort order will be by DOI update date.
@@ -226,7 +226,7 @@ CrossRef also has member IDs for depositing organisations. A single member may c
 
 ### Notes on dates
 
-Note that dates in filters should always be of the form `YYYY-MM-DD`, `YYYY-MM` or `YYYY`. Also not 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
 

From 305daa7357627ded03bbefa945dc5717c999082f Mon Sep 17 00:00:00 2001
From: Geoffrey Bilder 
Date: Thu, 24 Apr 2014 16:36:53 +0100
Subject: [PATCH 048/219] adding worked example

---
 ...t_syndication_through_crossref_metadata.md | 98 ++++++++++++++++---
 1 file changed, 86 insertions(+), 12 deletions(-)

diff --git a/content_syndication_through_crossref_metadata.md b/content_syndication_through_crossref_metadata.md
index 84147a7..b9ac010 100644
--- a/content_syndication_through_crossref_metadata.md
+++ b/content_syndication_through_crossref_metadata.md
@@ -5,13 +5,14 @@
 ## Version History
 
 - V1 2014-01-08, Initial draft
+  V2 2014-04-23, Add examples
 
 ## The Problem
 
 There is concern that the CrossRef schema does not give enough information to users about which resources are appropriate for different user classes and/or applications. For example, a publisher might want to be able to provide different lists of resources for the following use cases:
 
-- A human subscriber accessing the content to read 
-- A human non-subscriber accessing the content to read 
+- A human subscriber accessing the content to read
+- A human non-subscriber accessing the content to read
 - A human from an entitled funding agency accessing the content to read
 
 - A bot run by a subscriber accessing the content to TDM
@@ -47,13 +48,13 @@ Selecting the appropriate resource would seem to hinge on three criteria:
 
 We have used the term "BAV" to describe the "Best Available Version."- where "version" refers to the JATS version of a document (i.e. AAM, VOR). The idea is that some versions of the document (e.g. VOR) may be under restricted access (e.g. under embargo, require a subscription) and are thus "unavailable" to certain classes of user, while other versions of the document (e.g. AAM) are not under restrictions and are thus "available" to the respective class of user.
 
-But the above use-cases introduce another facet that may need to be considered when selecting a resource- the "Appropriate Application Resource" (AAR). That is, the use-cases above imply that publishers might want to direct users at resources pointing to systems that are optimized to support a particular application. For example, a publisher might have a server that is reserved for search engines, or for syndication partners, etc. 
+But the above use-cases introduce another facet that may need to be considered when selecting a resource- the "Appropriate Application Resource" (AAR). That is, the use-cases above imply that publishers might want to direct users at resources pointing to systems that are optimised to support a particular application. For example, a publisher might have a server that is reserved for search engines, another for syndication partners, etc.
 
 ## Providing Hints For Selecting a BAV
 
 The normative HTTP mechanism to handle these requirements technically, would be to use content negotiation. That is, an agent could request a resource using a GET and be shown the options for different available versions of the resource in the response headers. The user agent would then select the BAV/AAR from the options presented in the publisher's response. In other words, ideally the system would work the same way that content negotiation works for languages or for browser feature sets.
 
-However, CrossRef recognizes that, in the short/medium term, it would be impractical to expect all of our members to integrate such content negotiation in their publishing sites. Thus we have added the ability for publisher to record attributes of the resource that one would normally use content negotiation for in selecting a BAV. Specifically, we have added the following two attributes to the resource element:
+However, CrossRef recognises that, in the short/medium term, it would be impractical to expect all of our members to integrate such content negotiation in their publishing sites. Thus we have added the ability for publisher to record attributes of the resource that one would normally use content negotiation for in selecting a BAV. Specifically, we have added the following two attributes to the resource element:
 
 - mime_type
 - content_version
@@ -75,28 +76,101 @@ However, CrossRef recognizes that, in the short/medium term, it would be impract
     http://creativecommons.org/licenses/by/3.0/deed.en_US
 
 
-The addition of the `AccessIndicators` allows the publisher to indicate not only what versions of the resource **exist** , but also for the publisher to provide a mechanism for the user to determine a-priori (without doing an HTTP get for content negotiation) which versions of the resource are likely to be **available**. In short, the combination of `//AccessIndicator` elements and `//collection/resource` elements allows the user to determine the **BAV**. 
+The addition of the `AccessIndicators` allows the publisher to indicate not only what versions of the resource **exist** , but also for the publisher to provide a mechanism for the user to determine a-priori (without doing an HTTP get for content negotiation) which versions of the resource are likely to be **available**. In short, the combination of `//AccessIndicator` elements and `//collection/resource` elements allows the user to determine the **BAV**.
 
-## Providing Hints For Selecting a AAR
+## Providing Hints For Selecting an AAR
 
 But this still leaves us with the question of how to provide the publisher to provide the user with hints as to which version of a resource is appropriate for a particular application. So-far we have identified the following applications:
 
-1) Viewing (e.g. on the publisher's web site, via landing page, etc.)
-2) Indexing (e.g. for search engines, etc.)
+ 1. Viewing (e.g. on the publisher's web site, via landing page, etc.)
+ 2. Indexing (e.g. for search engines, etc.)
 
 
- Currently we already have three existing mechanisms for labeling different 'applications' of the resource. 
+ Currently we already have three existing mechanisms for labeling different 'applications' of the resource.
 
- The first mechanism is implicit. That is  `/doi_data/resource` attributes have normatively recorded a link to the publisher landing page, from which the human reader can get a "viewable" version of the resource. 
+ The first mechanism is implicit. That is  `/doi_data/resource` attributes have normatively recorded a link to the publisher landing page, from which the human reader can get a "viewable" version of the resource.
 
  The second two are encoded in the the `property` attribute of the `` container element. We currently support several values for this property, including `crawler-based` which was intended to be used to identify resources for search engines (i.e. indexing) and `text-mining` which has been introduced for resources designed for TDM bots. What seems to be missing is a value for "syndication." If we were to add a `syndication` attribute value then publishers would be able to record `/collection/resource` elements that meet all the use-cases identified above.  
 
- ## Limitations of proposed system
+ ## Putting it all together
+
+ If we combine the concept of the BAV and the AAR, we can meet all of the requirements outlined at the start of this document.
+
+ The following example for the sample DOI 10.5555/12345678 says:
+
+1. The VOR is under a year embargo (proprietary license) from the date of publication  
+2. After the year, the VOR is available under a CC-BY license
+3. The AAM is available under a CC-BY license from the date of publication
+4. The humans clicking on the link will be directed to the landing page on the publisher's site
+5. That robots requesting the content for a search engine (VOR only) should look for the PDF on the server `docstore.psychoceramics.org`. Access will be restricted as per the publisher's access control system.
+6. That robots requesting the content for syndication (AAM or VOR) should look for the PDF on the server `docstore.psychoceramics.org`. Access will be restricted as per the publisher's access control system.
+7. That robots requesting the content for text and data mining (AAM or VOR) should look for the XML on the server `marklogic.psychoceramics.org`. Access will be restricted as per the publisher's access control system.
+
+
+
+### example
+
+    
+        10.5555/12345678
+        20121025161509
+        
+          http://psychoceramics.labs.crossref.org/10.5555-12345678.html
+        
+    
+
+    
+    http://www.psychoceramics.org/license_v1.html
+    http://creativecommons.org/licenses/by/3.0/deed.en_US
+    http://creativecommons.org/licenses/by/3.0/deed.en_US
+
+    
+      
+          http://marklogic.psychoceramics.org/fulltext/vor/10.5555/12345678.xml
+      
+      
+          http://marklogic.psychoceramics.org/fulltext/am/10.5555/12345678.xml
+      
+    
+
+    
+      
+        http://docstore.psychoceramics.org/fulltext/vor/10.5555/12345678.pdf
+      
+      
+        http://docstore.psychoceramics.org/fulltext/am/10.5555/12345678.pdf
+      
+    
+
+    
+        
+            
+                http://docstore.psychoceramics.org/fulltext/vor/10.5555/12345678.pdf
+            
+        
+        
+            
+                http://docstore.psychoceramics.org/fulltext/vor/10.5555/12345678.pdf
+            
+        
+    
+
 
- The hints provided in CrossRef metadata are just that, hints. There is nothing that CrossRef can do to force users to select an particular resource appropriate to their application. Thus, it is still going to be the responsibility of the publisher to check requests and to route them appropriately. 
 
 
 
+## Open Questions
 
+We have suggested that the following values be used for AAR
+
+- crawler-based (search engines)
+- text-mining
+- syndication
+
+Are they enough?
+
+
+ ## Limitations of proposed system
 
+The hints provided in CrossRef metadata are just that, hints. There is nothing that CrossRef can do to force users to select an particular resource appropriate to their application. Thus, it is still going to be the responsibility of the publisher to check requests and to route them appropriately.
 
+We have made a tradeoff in implementation. We have not normalized the element/attribute combinations and, therefor therefor the suytem is quite verbose- particularly for the simplest case where a publisher wants to record the same resources for each AAR.

From 377f08a08a65fc221eb5b793a39c6adff42ed574 Mon Sep 17 00:00:00 2001
From: Karl Jonathan Ward 
Date: Thu, 24 Apr 2014 16:45:16 +0100
Subject: [PATCH 049/219] Correct vor, am in overall example

---
 content_syndication_through_crossref_metadata.md | 7 +++----
 1 file changed, 3 insertions(+), 4 deletions(-)

diff --git a/content_syndication_through_crossref_metadata.md b/content_syndication_through_crossref_metadata.md
index b9ac010..f2c15c4 100644
--- a/content_syndication_through_crossref_metadata.md
+++ b/content_syndication_through_crossref_metadata.md
@@ -1,5 +1,4 @@
 
-
 # Content Syndication Through CrossRef Metadata
 
 ## Version History
@@ -119,9 +118,9 @@ But this still leaves us with the question of how to provide the publisher to pr
     
 
     
-    http://www.psychoceramics.org/license_v1.html
-    http://creativecommons.org/licenses/by/3.0/deed.en_US
-    http://creativecommons.org/licenses/by/3.0/deed.en_US
+    http://www.psychoceramics.org/license_v1.html
+    http://creativecommons.org/licenses/by/3.0/deed.en_US
+    http://creativecommons.org/licenses/by/3.0/deed.en_US
 
     
       

From 31ee067b3ffff63a2985aca5efc68bd316f894c7 Mon Sep 17 00:00:00 2001
From: Karl Jonathan Ward 
Date: Fri, 25 Apr 2014 10:02:34 +0100
Subject: [PATCH 050/219] Add 'any' collection property type

---
 ...t_syndication_through_crossref_metadata.md | 65 +++++++++++++++----
 1 file changed, 51 insertions(+), 14 deletions(-)

diff --git a/content_syndication_through_crossref_metadata.md b/content_syndication_through_crossref_metadata.md
index f2c15c4..c867e83 100644
--- a/content_syndication_through_crossref_metadata.md
+++ b/content_syndication_through_crossref_metadata.md
@@ -1,10 +1,11 @@
 
-# Content Syndication Through CrossRef Metadata
+# Intended Use Hints Through CrossRef Metadata
 
 ## Version History
 
 - V1 2014-01-08, Initial draft
-  V2 2014-04-23, Add examples
+- V2 2014-04-23, Add examples
+- V3 2014-04-24, Add 'any' collection property type
 
 ## The Problem
 
@@ -91,7 +92,7 @@ But this still leaves us with the question of how to provide the publisher to pr
 
  The second two are encoded in the the `property` attribute of the `` container element. We currently support several values for this property, including `crawler-based` which was intended to be used to identify resources for search engines (i.e. indexing) and `text-mining` which has been introduced for resources designed for TDM bots. What seems to be missing is a value for "syndication." If we were to add a `syndication` attribute value then publishers would be able to record `/collection/resource` elements that meet all the use-cases identified above.  
 
- ## Putting it all together
+## Putting It All Together
 
  If we combine the concept of the BAV and the AAR, we can meet all of the requirements outlined at the start of this document.
 
@@ -105,9 +106,7 @@ But this still leaves us with the question of how to provide the publisher to pr
 6. That robots requesting the content for syndication (AAM or VOR) should look for the PDF on the server `docstore.psychoceramics.org`. Access will be restricted as per the publisher's access control system.
 7. That robots requesting the content for text and data mining (AAM or VOR) should look for the XML on the server `marklogic.psychoceramics.org`. Access will be restricted as per the publisher's access control system.
 
-
-
-### example
+### XML Example
 
     
         10.5555/12345678
@@ -123,39 +122,68 @@ But this still leaves us with the question of how to provide the publisher to pr
     http://creativecommons.org/licenses/by/3.0/deed.en_US
 
     
-      
+      
           http://marklogic.psychoceramics.org/fulltext/vor/10.5555/12345678.xml
       
-      
+      
           http://marklogic.psychoceramics.org/fulltext/am/10.5555/12345678.xml
       
     
 
     
-      
+      
         http://docstore.psychoceramics.org/fulltext/vor/10.5555/12345678.pdf
       
-      
+      
         http://docstore.psychoceramics.org/fulltext/am/10.5555/12345678.pdf
       
     
 
     
         
-            
+            
                 http://docstore.psychoceramics.org/fulltext/vor/10.5555/12345678.pdf
             
         
         
-            
+            
                 http://docstore.psychoceramics.org/fulltext/vor/10.5555/12345678.pdf
             
         
     
 
+## An 'any' Use Type
 
+Some members will not want to provide intended use hints. These members can avoid repetition, and ignore intended use hints
+altogether by using the 'any' collection property:
 
+    
+		10.5555/12345678
+        20121025161509
+        
+          http://psychoceramics.labs.crossref.org/10.5555-12345678.html
+        
+    
 
+    
+    http://www.psychoceramics.org/license_v1.html
+    http://creativecommons.org/licenses/by/3.0/deed.en_US
+    http://creativecommons.org/licenses/by/3.0/deed.en_US
+
+    
+      
+          http://docstore.psychoceramics.org/fulltext/vor/10.5555/12345678.xml
+      
+      
+          http://docstore.psychoceramics.org/fulltext/am/10.5555/12345678.xml
+      
+	  
+        http://docstore.psychoceramics.org/fulltext/vor/10.5555/12345678.pdf
+      
+      
+        http://docstore.psychoceramics.org/fulltext/am/10.5555/12345678.pdf
+      
+    
 
 ## Open Questions
 
@@ -164,12 +192,21 @@ We have suggested that the following values be used for AAR
 - crawler-based (search engines)
 - text-mining
 - syndication
+- any
 
 Are they enough?
 
-
- ## Limitations of proposed system
+## Limitations of Proposed System
 
 The hints provided in CrossRef metadata are just that, hints. There is nothing that CrossRef can do to force users to select an particular resource appropriate to their application. Thus, it is still going to be the responsibility of the publisher to check requests and to route them appropriately.
 
 We have made a tradeoff in implementation. We have not normalized the element/attribute combinations and, therefor therefor the suytem is quite verbose- particularly for the simplest case where a publisher wants to record the same resources for each AAR.
+
+## Access Control
+
+Intended use hints do not imply the existence or lack of access control. A publisher may choose to, or choose not to incorporate access control into links intended for text and data mining or content syndication. This follows the same situation for DOI resolution URLs, where some publishers place access control on some article landing pages. The decision to use or not use access control is left to the publisher, and will most likely be made after consideration of content licensing, collection of APCs, journal business model, government policy and participation in various industry-wide initiatives.
+
+## Removal of 'tdm' content_version
+
+This proposed system negates the need for a 'tdm' content version. An implementation of this proposal will also remove the 'tdm' option from
+the content_version resource attribute.

From e503bc8bbb59aea54ad466b1e567e86be7737a99 Mon Sep 17 00:00:00 2001
From: Karl Jonathan Ward 
Date: Fri, 25 Apr 2014 10:07:09 +0100
Subject: [PATCH 051/219] Title change

---
 content_syndication_through_crossref_metadata.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/content_syndication_through_crossref_metadata.md b/content_syndication_through_crossref_metadata.md
index c867e83..ffb4260 100644
--- a/content_syndication_through_crossref_metadata.md
+++ b/content_syndication_through_crossref_metadata.md
@@ -1,5 +1,5 @@
 
-# Intended Use Hints Through CrossRef Metadata
+# Resource Intended Use Hints Through CrossRef Metadata
 
 ## Version History
 

From 4390254194ea7f094d7b8a6606b2ae00a6d3029b Mon Sep 17 00:00:00 2001
From: Karl Jonathan Ward 
Date: Fri, 25 Apr 2014 10:10:39 +0100
Subject: [PATCH 052/219] Renamed resource intended use doc

---
 ...through_crossref_metadata.md => resource_intended_use_hints.md | 0
 1 file changed, 0 insertions(+), 0 deletions(-)
 rename content_syndication_through_crossref_metadata.md => resource_intended_use_hints.md (100%)

diff --git a/content_syndication_through_crossref_metadata.md b/resource_intended_use_hints.md
similarity index 100%
rename from content_syndication_through_crossref_metadata.md
rename to resource_intended_use_hints.md

From c526df3fa32e52b77d4c4679e96dc1ec9bef038c Mon Sep 17 00:00:00 2001
From: Karl Jonathan Ward 
Date: Fri, 25 Apr 2014 10:19:53 +0100
Subject: [PATCH 053/219] Remove 'verbose' discussion in limitations section

---
 resource_intended_use_hints.md | 4 +---
 1 file changed, 1 insertion(+), 3 deletions(-)

diff --git a/resource_intended_use_hints.md b/resource_intended_use_hints.md
index ffb4260..85a9d73 100644
--- a/resource_intended_use_hints.md
+++ b/resource_intended_use_hints.md
@@ -9,7 +9,7 @@
 
 ## The Problem
 
-There is concern that the CrossRef schema does not give enough information to users about which resources are appropriate for different user classes and/or applications. For example, a publisher might want to be able to provide different lists of resources for the following use cases:
+The CrossRef schema does not give enough information to users about which resources are appropriate for different user classes and/or applications. For example, a publisher might want to be able to provide different lists of resources for the following use cases:
 
 - A human subscriber accessing the content to read
 - A human non-subscriber accessing the content to read
@@ -200,8 +200,6 @@ Are they enough?
 
 The hints provided in CrossRef metadata are just that, hints. There is nothing that CrossRef can do to force users to select an particular resource appropriate to their application. Thus, it is still going to be the responsibility of the publisher to check requests and to route them appropriately.
 
-We have made a tradeoff in implementation. We have not normalized the element/attribute combinations and, therefor therefor the suytem is quite verbose- particularly for the simplest case where a publisher wants to record the same resources for each AAR.
-
 ## Access Control
 
 Intended use hints do not imply the existence or lack of access control. A publisher may choose to, or choose not to incorporate access control into links intended for text and data mining or content syndication. This follows the same situation for DOI resolution URLs, where some publishers place access control on some article landing pages. The decision to use or not use access control is left to the publisher, and will most likely be made after consideration of content licensing, collection of APCs, journal business model, government policy and participation in various industry-wide initiatives.

From 3910d7c746cb9a167da9baefe42a6d1042220c8f Mon Sep 17 00:00:00 2001
From: Karl Jonathan Ward 
Date: Fri, 25 Apr 2014 16:35:51 +0100
Subject: [PATCH 054/219] Incorporate wording changes from Evan Owens

---
 resource_intended_use_hints.md | 16 +++++++---------
 1 file changed, 7 insertions(+), 9 deletions(-)

diff --git a/resource_intended_use_hints.md b/resource_intended_use_hints.md
index 85a9d73..76cbde6 100644
--- a/resource_intended_use_hints.md
+++ b/resource_intended_use_hints.md
@@ -6,6 +6,7 @@
 - V1 2014-01-08, Initial draft
 - V2 2014-04-23, Add examples
 - V3 2014-04-24, Add 'any' collection property type
+- V4 2014-04-25, Incorporate suggestions from Evan Owens
 
 ## The Problem
 
@@ -19,9 +20,9 @@ The CrossRef schema does not give enough information to users about which resour
 - A bot run by a non-subscriber accessing the content to TDM
 - A bot run by an entitled funding agency accessing the content to TDM
 
-- A bot run by a subscriber accessing the content to syndicate
-- A bot run by a non-subscriber accessing the content to syndicate
-- A bot run by an entitled funding agency accessing the content to syndicate
+- A bot run by a subscriber accessing the content under a syndication agreement
+- A bot run by a non-subscriber accessing the content under a syndication agreement
+- A bot run by an entitled funding agency accessing the content under a syndication agreement
 
 In the above cases, the content in question might or be either "restricted" (e.g.  requiring a subscription to access) or "unrestricted" (open access, free). Furthermore, any restrictions may be time-boxed via embargoes. This effectively means that their are sub-cases where the desired behavior might change depending on when the user (bot or human) tries to access the content.
 
@@ -46,7 +47,7 @@ Selecting the appropriate resource would seem to hinge on three criteria:
 - What is the desired application? Viewing, indexing, syndication, tdm?
 
 
-We have used the term "BAV" to describe the "Best Available Version."- where "version" refers to the JATS version of a document (i.e. AAM, VOR). The idea is that some versions of the document (e.g. VOR) may be under restricted access (e.g. under embargo, require a subscription) and are thus "unavailable" to certain classes of user, while other versions of the document (e.g. AAM) are not under restrictions and are thus "available" to the respective class of user.
+We have used the term "BAV" to describe the "Best Available Version."- where "version" refers to the [JAV](www.niso.org/publications/rp/RP-8-2008.pdf‎) version of a document (i.e. AAM, VOR). The idea is that some versions of the document (e.g. VOR) may be under restricted access (e.g. under embargo, require a subscription) and are thus "unavailable" to certain classes of user, while other versions of the document (e.g. AAM) are not under restrictions and are thus "available" to the respective class of user.
 
 But the above use-cases introduce another facet that may need to be considered when selecting a resource- the "Appropriate Application Resource" (AAR). That is, the use-cases above imply that publishers might want to direct users at resources pointing to systems that are optimised to support a particular application. For example, a publisher might have a server that is reserved for search engines, another for syndication partners, etc.
 
@@ -122,11 +123,11 @@ But this still leaves us with the question of how to provide the publisher to pr
     http://creativecommons.org/licenses/by/3.0/deed.en_US
 
     
-      
+      
           http://marklogic.psychoceramics.org/fulltext/vor/10.5555/12345678.xml
       
       
-          http://marklogic.psychoceramics.org/fulltext/am/10.5555/12345678.xml
+          http://docstore.psychoceramics.org/fulltext/am/10.5555/12345678.pdf
       
     
 
@@ -173,9 +174,6 @@ altogether by using the 'any' collection property:
     
       
           http://docstore.psychoceramics.org/fulltext/vor/10.5555/12345678.xml
-      
-      
-          http://docstore.psychoceramics.org/fulltext/am/10.5555/12345678.xml
       
 	  
         http://docstore.psychoceramics.org/fulltext/vor/10.5555/12345678.pdf

From 99326baac542d3d8e1337079556acb853183352d Mon Sep 17 00:00:00 2001
From: Karl Jonathan Ward 
Date: Fri, 25 Apr 2014 16:37:54 +0100
Subject: [PATCH 055/219] Correct formatting of some bulleted lists

---
 resource_intended_use_hints.md | 4 ----
 1 file changed, 4 deletions(-)

diff --git a/resource_intended_use_hints.md b/resource_intended_use_hints.md
index 76cbde6..62ec63b 100644
--- a/resource_intended_use_hints.md
+++ b/resource_intended_use_hints.md
@@ -15,11 +15,9 @@ The CrossRef schema does not give enough information to users about which resour
 - A human subscriber accessing the content to read
 - A human non-subscriber accessing the content to read
 - A human from an entitled funding agency accessing the content to read
-
 - A bot run by a subscriber accessing the content to TDM
 - A bot run by a non-subscriber accessing the content to TDM
 - A bot run by an entitled funding agency accessing the content to TDM
-
 - A bot run by a subscriber accessing the content under a syndication agreement
 - A bot run by a non-subscriber accessing the content under a syndication agreement
 - A bot run by an entitled funding agency accessing the content under a syndication agreement
@@ -31,10 +29,8 @@ In the above cases, the content in question might or be either "restricted" (e.g
 - A human readable landing page on the publisher's main website.
 - A human readable representation of the VOR (e.g. PDF, HTML, etc.) on the publisher's main website.
 - A human readable representation of the AAM (e.g. PDF, HTML, etc.) on the publisher's main website.
-
 - A machine readable representation of the VOR (e.g. XML, Plain Text) on the publisher's TDM server
 - A machine readable representation of the AAM (e.g. XML, Plain Text) on the publisher's TDM server
-
 - A human readable representation of the VOR (e.g. PDF, HTML, etc.) on the publisher's syndication server.
 - A human readable representation of the AAM (e.g. PDF, HTML, etc.) on the publisher's syndication server.
 

From 21fa38b9a7776457c6b650c9218eb4a38a883a60 Mon Sep 17 00:00:00 2001
From: Karl Jonathan Ward 
Date: Fri, 25 Apr 2014 16:47:34 +0100
Subject: [PATCH 056/219] Fix link to JAV

---
 resource_intended_use_hints.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/resource_intended_use_hints.md b/resource_intended_use_hints.md
index 62ec63b..5842a2f 100644
--- a/resource_intended_use_hints.md
+++ b/resource_intended_use_hints.md
@@ -43,7 +43,7 @@ Selecting the appropriate resource would seem to hinge on three criteria:
 - What is the desired application? Viewing, indexing, syndication, tdm?
 
 
-We have used the term "BAV" to describe the "Best Available Version."- where "version" refers to the [JAV](www.niso.org/publications/rp/RP-8-2008.pdf‎) version of a document (i.e. AAM, VOR). The idea is that some versions of the document (e.g. VOR) may be under restricted access (e.g. under embargo, require a subscription) and are thus "unavailable" to certain classes of user, while other versions of the document (e.g. AAM) are not under restrictions and are thus "available" to the respective class of user.
+We have used the term "BAV" to describe the "Best Available Version."- where "version" refers to the [JAV](http://www.niso.org/publications/rp/RP-8-2008.pdf‎) version of a document (i.e. AAM, VOR). The idea is that some versions of the document (e.g. VOR) may be under restricted access (e.g. under embargo, require a subscription) and are thus "unavailable" to certain classes of user, while other versions of the document (e.g. AAM) are not under restrictions and are thus "available" to the respective class of user.
 
 But the above use-cases introduce another facet that may need to be considered when selecting a resource- the "Appropriate Application Resource" (AAR). That is, the use-cases above imply that publishers might want to direct users at resources pointing to systems that are optimised to support a particular application. For example, a publisher might have a server that is reserved for search engines, another for syndication partners, etc.
 

From 96e60c771c7880d65a6df6537e9b822a79fe575c Mon Sep 17 00:00:00 2001
From: Karl Jonathan Ward 
Date: Fri, 25 Apr 2014 16:48:43 +0100
Subject: [PATCH 057/219] Fix link to JAV again (odd chars)

---
 resource_intended_use_hints.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/resource_intended_use_hints.md b/resource_intended_use_hints.md
index 5842a2f..2259be1 100644
--- a/resource_intended_use_hints.md
+++ b/resource_intended_use_hints.md
@@ -43,7 +43,7 @@ Selecting the appropriate resource would seem to hinge on three criteria:
 - What is the desired application? Viewing, indexing, syndication, tdm?
 
 
-We have used the term "BAV" to describe the "Best Available Version."- where "version" refers to the [JAV](http://www.niso.org/publications/rp/RP-8-2008.pdf‎) version of a document (i.e. AAM, VOR). The idea is that some versions of the document (e.g. VOR) may be under restricted access (e.g. under embargo, require a subscription) and are thus "unavailable" to certain classes of user, while other versions of the document (e.g. AAM) are not under restrictions and are thus "available" to the respective class of user.
+We have used the term "BAV" to describe the "Best Available Version."- where "version" refers to the [JAV](http://www.niso.org/publications/rp/RP-8-2008.pdf) version of a document (i.e. AAM, VOR). The idea is that some versions of the document (e.g. VOR) may be under restricted access (e.g. under embargo, require a subscription) and are thus "unavailable" to certain classes of user, while other versions of the document (e.g. AAM) are not under restrictions and are thus "available" to the respective class of user.
 
 But the above use-cases introduce another facet that may need to be considered when selecting a resource- the "Appropriate Application Resource" (AAR). That is, the use-cases above imply that publishers might want to direct users at resources pointing to systems that are optimised to support a particular application. For example, a publisher might have a server that is reserved for search engines, another for syndication partners, etc.
 

From f8be32711ab97f7c8f89aaefdde81d407be9adaf Mon Sep 17 00:00:00 2001
From: Karl Jonathan Ward 
Date: Tue, 13 May 2014 09:50:24 +0100
Subject: [PATCH 058/219] Fix link to rest api

---
 deposit_api.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/deposit_api.md b/deposit_api.md
index c4ed1d7..dc96e55 100644
--- a/deposit_api.md
+++ b/deposit_api.md
@@ -24,7 +24,7 @@ within the current CrossRef XML deposit mechanism.
 ## Extension to the CrossRef REST API
 
 This document provides an extension to the CrossRef REST API, described
-[here](http://github.com/CrossRef/rest-api-doc/funder_kpi_api.md). It uses the same
+[here](https://github.com/CrossRef/rest-api-doc/blob/master/funder_kpi_api.md). It uses the same
 API versioning scheme, JSON response format and concepts of singular and listy
 responses. The base URI for this API is:
 

From 2145619eb223991616c717eb6515999429e713da Mon Sep 17 00:00:00 2001
From: Karl Jonathan Ward 
Date: Mon, 19 May 2014 10:56:23 +0100
Subject: [PATCH 059/219] Document /journals, update and update policy filters,
 sorting

---
 funder_kpi_api.md | 35 +++++++++++++++++++++++++++++++----
 1 file changed, 31 insertions(+), 4 deletions(-)

diff --git a/funder_kpi_api.md b/funder_kpi_api.md
index 431b722..daf44c7 100644
--- a/funder_kpi_api.md
+++ b/funder_kpi_api.md
@@ -18,6 +18,7 @@
 - v13: 2014-02-10, new `/members`, `/publishers` becomes `/prefixes`, new `member` filter, `publisher` filter becomes `prefix`
 - v14: 2014-02-14, new `has-funder` filter.
 - v15: 2014-02-27, new `/licenses` route
+- v16: 2014-05-19, new `/journals` route, new CrossMark (updates and update policy) filters, new `sort` and `order` parameters
 
 ## Background
 
@@ -77,7 +78,6 @@ Lists results can contain multiple entries. Searching or filtering typically ret
     - message-version (e.g. 1.0.0 )
 - Items, which will will contain the items matching the query or filter. 
 
-
 Note that the "message-type" returned will differ from the mime-type:
 
 - funder (singleton)
@@ -89,7 +89,6 @@ Note that the "message-type" returned will differ from the mime-type:
 - prefix-list (list)
 - member-list (list)
 
-
 Normally, an API list result will return both the summary and the items. If you want to just retrieve the summary, you can do so by specifying that the number of rows returned should be zero. 
 ### Sort order
 
@@ -103,6 +102,8 @@ Major resource components supported by the CrossRef API are:
 - funders
 - members
 - prefixes
+- types
+- journals
 
 These can be used alone like this
 
@@ -113,6 +114,7 @@ These can be used alone like this
 | `/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 |
 
 
 ### Resource components and identifiers
@@ -125,6 +127,7 @@ Resource components can be used in conjunction with identifiers to retrieve the
 | `/prefixes/{owner_prefix}` | returns metadata for the DOI owner prefix |
 | `/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 |
 
 ### Combining resource components
 
@@ -134,10 +137,10 @@ The works component can be appended to other resources.
 |:----------------------------|:----------------------------------|
 | `/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}/works` | returns list of works of type `type` |
+| `/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) |
-
+| `/journals/{issn}/works` | returns a list of works in the given journal |
 
 ## Parameters
 
@@ -150,6 +153,8 @@ Parameters can be used to query, filter and control the results returned by the
 | `rows={#}`                   | results per per page | 
 | `offset={#}`                 | result offset |                         
 | `sample={#}`                 | return random N results |
+| `sort={#}`                   | sort results by a certain field |
+| `order={#}`                  | set the sort order to `asc` or `desc` |
 
 Multiple filters can be specified by separating name:value pairs with a comma:
 
@@ -179,6 +184,23 @@ or using JSON
 
     curl -X GET -H "Content-Type: application/json" -d '{"query": "renear -ontologies"}'  http://api.crossref.org/works
 
+## Sorting
+
+Results from a listy response can be sorted by applying the `sort` and `order` parameters. Order
+sets the result ordering, either `asc` or `desc`. Sort sets the field by which results will be
+sorted. Possible values are:
+
+| Sort value | Description |
+| `score` or `relevance` | Sort by relevance score |
+| `updated` | Sort by date of most recent change to metadata. Currently the same as `deposited`. |
+| `deposited` | Sort by time of most recent deposit |
+| `indexed` | Sort by time of most recent index |
+| `published` | Sort by publication date |
+
+An example that sorts results in order of publication, beginning with the least recent:
+
+    http://api.crossref.org/works?query=josiah+carberry&sort=published&order=asc
+
 ## Filter Names
 
 Filters allow you to narrow queries. All filter results are lists.  The following filters are supported:
@@ -208,6 +230,7 @@ Filters allow you to narrow queries. All filter results are lists.  The followin
 | `full-text.version` | `{string}`  | metadata where `` element's `content_version` attribute is `{string}`. |
 | `full-text.type` | `{mime_type}`  | metadata where `` element's `content_type` attribute is `{mime_type}` (e.g. `application/pdf`). |
 | `public-references` | | metadata where publishers allow references to be distributed publically. [^*] |
+| `has-references` | | metadata for works that have a list of references |
 | `has-archive` | | metadata which include name of archive partner |
 | `archive` | `{string}` | metadata which where value of archive partner is `{string}` |
 | `has-orcid` | | metadata which includes one or more ORCIDs |
@@ -215,6 +238,10 @@ Filters allow you to narrow queries. All filter results are lists.  The followin
 | `issn` | `{issn}` | metadata where record has an ISSN = `{issn}`. Format is `xxxx-xxxx`. |
 | `type` | `{type}` | metadata records whose type = `{type}`. Type must be an ID value from the list of types returned by the `/types` resource |
 | `directory` | `{directory}` | metadata records whose article or serial are mentioned in the given `{directory}`. Currently the only supported value is `doaj`. |
+| `doi` | `{doi}` | metadata describing the DOI `{doi}` |
+| `updates` | `{doi}` | metadata for records that represent editorial updates to the DOI `{doi}` |
+| `is-update` | | metadata for records that represent editorial updates |
+| `has-update-policy` | | metadata for records that include a link to an editorial update policy |
 
 [^*]: Not implemented yet.
 

From 7d5c1b418bd2d9b82eeaadda45f6f0a89b19ae70 Mon Sep 17 00:00:00 2001
From: Karl Jonathan Ward 
Date: Mon, 19 May 2014 11:18:30 +0100
Subject: [PATCH 060/219] Fix sort value table

---
 funder_kpi_api.md | 1 +
 1 file changed, 1 insertion(+)

diff --git a/funder_kpi_api.md b/funder_kpi_api.md
index daf44c7..25a63e5 100644
--- a/funder_kpi_api.md
+++ b/funder_kpi_api.md
@@ -191,6 +191,7 @@ sets the result ordering, either `asc` or `desc`. Sort sets the field by which r
 sorted. Possible values are:
 
 | Sort value | Description |
+|------------|-------------|
 | `score` or `relevance` | Sort by relevance score |
 | `updated` | Sort by date of most recent change to metadata. Currently the same as `deposited`. |
 | `deposited` | Sort by time of most recent deposit |

From 67584807f11359cb09aac523ed56c8a25e361fbd Mon Sep 17 00:00:00 2001
From: Karl Jonathan Ward 
Date: Mon, 19 May 2014 12:49:16 +0100
Subject: [PATCH 061/219] Add facet parameter info

---
 funder_kpi_api.md | 7 +++++++
 1 file changed, 7 insertions(+)

diff --git a/funder_kpi_api.md b/funder_kpi_api.md
index 25a63e5..15804a4 100644
--- a/funder_kpi_api.md
+++ b/funder_kpi_api.md
@@ -19,6 +19,7 @@
 - v14: 2014-02-14, new `has-funder` filter.
 - v15: 2014-02-27, new `/licenses` route
 - v16: 2014-05-19, new `/journals` route, new CrossMark (updates and update policy) filters, new `sort` and `order` parameters
+- v17: 2014-05-19, new `facet` query parameter
 
 ## Background
 
@@ -155,6 +156,7 @@ Parameters can be used to query, filter and control the results returned by the
 | `sample={#}`                 | return random N results |
 | `sort={#}`                   | sort results by a certain field |
 | `order={#}`                  | set the sort order to `asc` or `desc` |
+| `facet=t`                    | enable facet information in responses |
 
 Multiple filters can be specified by separating name:value pairs with a comma:
 
@@ -202,6 +204,11 @@ An example that sorts results in order of publication, beginning with the least
 
     http://api.crossref.org/works?query=josiah+carberry&sort=published&order=asc
 
+## Facet Counts
+
+Facet counts can be retrieved by enabling faceting; `facet=t` (or `1`, `true`). Facet counts
+give counts per field value for an entire result set.
+
 ## Filter Names
 
 Filters allow you to narrow queries. All filter results are lists.  The following filters are supported:

From 000d86993e094f6fe0ce06b381212e7f9511d53e Mon Sep 17 00:00:00 2001
From: Karl Jonathan Ward 
Date: Tue, 27 May 2014 14:21:00 +0100
Subject: [PATCH 062/219] Rename 'any' intended use to 'unspecified'.

---
 resource_intended_use_hints.md | 9 +++++----
 1 file changed, 5 insertions(+), 4 deletions(-)

diff --git a/resource_intended_use_hints.md b/resource_intended_use_hints.md
index 2259be1..4d3f2ca 100644
--- a/resource_intended_use_hints.md
+++ b/resource_intended_use_hints.md
@@ -7,6 +7,7 @@
 - V2 2014-04-23, Add examples
 - V3 2014-04-24, Add 'any' collection property type
 - V4 2014-04-25, Incorporate suggestions from Evan Owens
+- V5 2014-05-27, Rename 'any' to 'unspecified'
 
 ## The Problem
 
@@ -149,10 +150,10 @@ But this still leaves us with the question of how to provide the publisher to pr
         
     
 
-## An 'any' Use Type
+## An 'unspecified' Use Type
 
 Some members will not want to provide intended use hints. These members can avoid repetition, and ignore intended use hints
-altogether by using the 'any' collection property:
+altogether by using the 'unspecified' collection property:
 
     
 		10.5555/12345678
@@ -167,7 +168,7 @@ altogether by using the 'any' collection property:
     http://creativecommons.org/licenses/by/3.0/deed.en_US
     http://creativecommons.org/licenses/by/3.0/deed.en_US
 
-    
+    
       
           http://docstore.psychoceramics.org/fulltext/vor/10.5555/12345678.xml
       
@@ -186,7 +187,7 @@ We have suggested that the following values be used for AAR
 - crawler-based (search engines)
 - text-mining
 - syndication
-- any
+- unspecified
 
 Are they enough?
 

From 2b0da6a079f65b33fb8988fdbde834351883f903 Mon Sep 17 00:00:00 2001
From: Karl Jonathan Ward 
Date: Thu, 29 May 2014 10:44:27 +0100
Subject: [PATCH 063/219] Document new /works/:doi/agency route

---
 funder_kpi_api.md | 31 ++++++++++++++++++++-----------
 1 file changed, 20 insertions(+), 11 deletions(-)

diff --git a/funder_kpi_api.md b/funder_kpi_api.md
index 15804a4..dd1561d 100644
--- a/funder_kpi_api.md
+++ b/funder_kpi_api.md
@@ -20,6 +20,7 @@
 - v15: 2014-02-27, new `/licenses` route
 - v16: 2014-05-19, new `/journals` route, new CrossMark (updates and update policy) filters, new `sort` and `order` parameters
 - v17: 2014-05-19, new `facet` query parameter
+- v18: 2014-05-29, new `/works/{doi}/agency` route
 
 ## Background
 
@@ -36,25 +37,34 @@ The API described here is in alpha. If you encounter problems with the API or th
 
 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 convention:
+The API will only work for CrossRef DOIs. You can test the registration agency for a DOI using the following route:
 
-`http://doi.crossref.org/doiRA/{doi}`
+`http://api.crossref.org/works/{doi}/agency`
 
-So testing the following CrossRef DOI:
+Testing the following CrossRef DOI:
 
 `10.1037/0003-066X.59.1.29`
 
+Using the URL:
+
+`http://api.crossref.org/works/10.1037/0003-066X.59.1.29/agency`
+
 Will return the following result:
 
-    [
-        {
-             DOI: "10.1037/0003-066X.59.1.29",
-             RA: "CrossRef"
+    {
+      status: "ok",
+      message-type: "work-agency",
+      message-version: "1.0.0",
+      message: {
+        DOI: "10.1037/0003-066x.59.1.29",
+        agency: {
+          id: "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 with the message "non-CrossRef DOI."
+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
 
@@ -213,7 +223,6 @@ give counts per field value for an entire result set.
 
 Filters allow you to narrow queries. All filter results are lists.  The following filters are supported:
 
-
 | filter     | possible values | description|
 |:-----------|:----------------|:-----------|
 | `has-funder` | | metadata which includes one or more funder entry |

From 6e6d233cbccde306168ae6c1bbf36fb51d70a6d1 Mon Sep 17 00:00:00 2001
From: Geoffrey Bilder 
Date: Tue, 3 Jun 2014 11:00:50 +0100
Subject: [PATCH 064/219] Fixed duplicate example that should have had rows set
 to maxrows.

---
 rest_api_tour.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/rest_api_tour.md b/rest_api_tour.md
index 6ce79c3..26b0f35 100644
--- a/rest_api_tour.md
+++ b/rest_api_tour.md
@@ -92,7 +92,7 @@ Ok, lets see how many records with the word "blood" in the metadata have license
 
 Let's download the results and download the content locally to TDM
 
-    http://api.crossref.org/works?filter=has-license:true,has-full-text:true&query=blood&rows=0
+    http://api.crossref.org/works?filter=has-license:true,has-full-text:true&query=blood&rows=884
 
 
 

From dbefe00d45a0d05b739b04917c654c3b3b1e0413 Mon Sep 17 00:00:00 2001
From: Karl Jonathan Ward 
Date: Mon, 23 Jun 2014 12:17:50 +0100
Subject: [PATCH 065/219] Add textual filters for work metadata

---
 funder_kpi_api.md | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/funder_kpi_api.md b/funder_kpi_api.md
index dd1561d..2c35a20 100644
--- a/funder_kpi_api.md
+++ b/funder_kpi_api.md
@@ -21,6 +21,7 @@
 - v16: 2014-05-19, new `/journals` route, new CrossMark (updates and update policy) filters, new `sort` and `order` parameters
 - v17: 2014-05-19, new `facet` query parameter
 - v18: 2014-05-29, new `/works/{doi}/agency` route
+- v19: 2014-06-23, new textual filters - `container-title`, `publisher-name`, `category-name`.
 
 ## Background
 
@@ -259,6 +260,9 @@ Filters allow you to narrow queries. All filter results are lists.  The followin
 | `updates` | `{doi}` | metadata for records that represent editorial updates to the DOI `{doi}` |
 | `is-update` | | metadata for records that represent editorial updates |
 | `has-update-policy` | | metadata for records that include a link to an editorial update policy |
+| `container-title` | metadata for records with a publication title exactly with an exact match |
+| `publisher-name` | metadata for records with an exact matching publisher name |
+| `category-name` | metadata for records with an exact matching category label |
 
 [^*]: Not implemented yet.
 

From 6bbcc26f9ba7995e0cdbc2dbbf62a7c2a0c5ac31 Mon Sep 17 00:00:00 2001
From: Karl Jonathan Ward 
Date: Tue, 24 Jun 2014 13:04:52 +0100
Subject: [PATCH 066/219] Update funder_kpi_api.md

---
 funder_kpi_api.md | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/funder_kpi_api.md b/funder_kpi_api.md
index 2c35a20..90beaf8 100644
--- a/funder_kpi_api.md
+++ b/funder_kpi_api.md
@@ -22,6 +22,7 @@
 - v17: 2014-05-19, new `facet` query parameter
 - v18: 2014-05-29, new `/works/{doi}/agency` route
 - v19: 2014-06-23, new textual filters - `container-title`, `publisher-name`, `category-name`.
+- v20: 2014-06-34, OR filter queries, `type-name` filter.
 
 ## Background
 
@@ -263,6 +264,7 @@ Filters allow you to narrow queries. All filter results are lists.  The followin
 | `container-title` | metadata for records with a publication title exactly with an exact match |
 | `publisher-name` | metadata for records with an exact matching publisher name |
 | `category-name` | metadata for records with an exact matching category label |
+| `type-name` | metadata for records with an exacty matching type label |
 
 [^*]: Not implemented yet.
 

From 2fbfec2fac46003c50326f8c897aef3373b42306 Mon Sep 17 00:00:00 2001
From: Karl Jonathan Ward 
Date: Tue, 24 Jun 2014 13:05:08 +0100
Subject: [PATCH 067/219] Update funder_kpi_api.md

---
 funder_kpi_api.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/funder_kpi_api.md b/funder_kpi_api.md
index 90beaf8..3a9b547 100644
--- a/funder_kpi_api.md
+++ b/funder_kpi_api.md
@@ -22,7 +22,7 @@
 - v17: 2014-05-19, new `facet` query parameter
 - v18: 2014-05-29, new `/works/{doi}/agency` route
 - v19: 2014-06-23, new textual filters - `container-title`, `publisher-name`, `category-name`.
-- v20: 2014-06-34, OR filter queries, `type-name` filter.
+- v20: 2014-06-24, OR filter queries, `type-name` filter.
 
 ## Background
 

From 8009c12234b0a6cd907d87259924344c0564ff0d Mon Sep 17 00:00:00 2001
From: Karl Jonathan Ward 
Date: Tue, 24 Jun 2014 13:05:37 +0100
Subject: [PATCH 068/219] Update funder_kpi_api.md

---
 funder_kpi_api.md | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/funder_kpi_api.md b/funder_kpi_api.md
index 3a9b547..cf80bec 100644
--- a/funder_kpi_api.md
+++ b/funder_kpi_api.md
@@ -261,10 +261,10 @@ Filters allow you to narrow queries. All filter results are lists.  The followin
 | `updates` | `{doi}` | metadata for records that represent editorial updates to the DOI `{doi}` |
 | `is-update` | | metadata for records that represent editorial updates |
 | `has-update-policy` | | metadata for records that include a link to an editorial update policy |
-| `container-title` | metadata for records with a publication title exactly with an exact match |
-| `publisher-name` | metadata for records with an exact matching publisher name |
-| `category-name` | metadata for records with an exact matching category label |
-| `type-name` | metadata for records with an exacty matching type label |
+| `container-title` | | metadata for records with a publication title exactly with an exact match |
+| `publisher-name` | | metadata for records with an exact matching publisher name |
+| `category-name` | | metadata for records with an exact matching category label |
+| `type-name` | | metadata for records with an exacty matching type label |
 
 [^*]: Not implemented yet.
 

From 9cad614f45aa087852ca5426d179a2cc8904626d Mon Sep 17 00:00:00 2001
From: Karl Jonathan Ward 
Date: Tue, 1 Jul 2014 13:53:16 +0100
Subject: [PATCH 069/219] New award relational filters:

award.number, award.funder
---
 funder_kpi_api.md | 7 +++++++
 1 file changed, 7 insertions(+)

diff --git a/funder_kpi_api.md b/funder_kpi_api.md
index cf80bec..a38c129 100644
--- a/funder_kpi_api.md
+++ b/funder_kpi_api.md
@@ -23,6 +23,7 @@
 - v18: 2014-05-29, new `/works/{doi}/agency` route
 - v19: 2014-06-23, new textual filters - `container-title`, `publisher-name`, `category-name`.
 - v20: 2014-06-24, OR filter queries, `type-name` filter.
+- v21: 2014-07-01, new `award.number` and `award.funder` relational filters.
 
 ## Background
 
@@ -265,6 +266,8 @@ Filters allow you to narrow queries. All filter results are lists.  The followin
 | `publisher-name` | | metadata for records with an exact matching publisher name |
 | `category-name` | | metadata for records with an exact matching category label |
 | `type-name` | | metadata for records with an exacty matching type label |
+| `award.number` | `{award_number}` | metadata for records with a matching award nunber. Optionally combine with `award.funder` |
+| `award.funder` | `{funder doi or id}` | metadata for records with an award with matching funder. Optionally combine with `award.number` |
 
 [^*]: Not implemented yet.
 
@@ -352,6 +355,10 @@ Note that the filters for license URL and maximum license embargo period (licens
 **All licenses applied to works published in the journal `Pathology Research International`**
 
     http://api.crossref.org/licenses?filter=issn:2090-8091
+    
+**All works with an award numbered roughly `1 F31 MH11745` also awarded by funder with ID `10.13039/100000025`:
+
+    http://api.crossref.org/works?filter=award.number:1F31MH11745,award.funder:10.13039/100000025
 
 ## Versioning
 

From cfdfba1b1293a649ac056126d9276656d4b8fd86 Mon Sep 17 00:00:00 2001
From: Geoffrey Bilder 
Date: Wed, 16 Jul 2014 02:57:57 +0200
Subject: [PATCH 070/219] Update funder_kpi_api.md

changed title to more accurately reflect scope of API
---
 funder_kpi_api.md | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/funder_kpi_api.md b/funder_kpi_api.md
index a38c129..8ab1797 100644
--- a/funder_kpi_api.md
+++ b/funder_kpi_api.md
@@ -1,4 +1,4 @@
-# CrossRef APIs to support key performance indicators (KPIs) for funding agencies
+# CrossRef REST API
 
 ## Version History
 
@@ -24,6 +24,7 @@
 - v19: 2014-06-23, new textual filters - `container-title`, `publisher-name`, `category-name`.
 - v20: 2014-06-24, OR filter queries, `type-name` filter.
 - 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. 
 
 ## Background
 

From 67f44f31dd9e48e0e87f03be324767de6bfc28a1 Mon Sep 17 00:00:00 2001
From: Karl Jonathan Ward 
Date: Mon, 21 Jul 2014 12:33:08 +0100
Subject: [PATCH 071/219] Rename funder_kpi_api to rest_api

---
 funder_kpi_api.md | 398 +--------------------------------------------
 rest_api.md       | 399 ++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 401 insertions(+), 396 deletions(-)
 create mode 100644 rest_api.md

diff --git a/funder_kpi_api.md b/funder_kpi_api.md
index 8ab1797..4f12822 100644
--- a/funder_kpi_api.md
+++ b/funder_kpi_api.md
@@ -1,399 +1,5 @@
 # CrossRef REST API
 
-## Version History
+This documentation has moved. Please [click here](http://api.crossref.org) to get to the new location.
 
-- V1: 2013-09-08, first draft.
-- V2: 2013-09-24, reference platform deployed
-- v3: 2013-09-25, reworked filters. Added API versioning doc 
-- v4: 2013-09-25, more filter changes.
-- v5: 2013-09-27, doc mime-type and message-type relationship
-- v6: 2013-10-01, updated `sample` & added examples with filters
-- v6: 2013-10-01, corrected warning date
-- v7: 2013-10-02, fixed typos
-- v8: 2013-10-17, updated warning. Added email address
-- v9: 2013-12-13, update example urls
-- v10: 2013-12-13, /types routes, type filter, issn filter
-- v11: 2013-12-14, indexed timestamps, has-archive and archive implemented
-- v12: 2014-01-06, directory filter
-- v13: 2014-02-10, new `/members`, `/publishers` becomes `/prefixes`, new `member` filter, `publisher` filter becomes `prefix`
-- v14: 2014-02-14, new `has-funder` filter.
-- v15: 2014-02-27, new `/licenses` route
-- v16: 2014-05-19, new `/journals` route, new CrossMark (updates and update policy) filters, new `sort` and `order` parameters
-- v17: 2014-05-19, new `facet` query parameter
-- v18: 2014-05-29, new `/works/{doi}/agency` route
-- v19: 2014-06-23, new textual filters - `container-title`, `publisher-name`, `category-name`.
-- v20: 2014-06-24, OR filter queries, `type-name` filter.
-- 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. 
-
-## Background
-
-See the document, [CrossRef metadata best practice to support key performance indicators (KPIs) for funding agencies](http://api.crossref.org/docs/funder_kpi_metadata_best_practice.html), for background.
-
-## Warning
-
-The API described here is in alpha. If you encounter problems with the API or the documentation, please report them to:
-
-![](http://labs.crossref.org/wp-content/uploads/2013/01/labs_email.png)
-
-
-## 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:
-
-`http://api.crossref.org/works/{doi}/agency`
-
-Testing the following CrossRef DOI:
-
-`10.1037/0003-066X.59.1.29`
-
-Using the URL:
-
-`http://api.crossref.org/works/10.1037/0003-066X.59.1.29/agency`
-
-Will return the following result:
-
-    {
-      status: "ok",
-      message-type: "work-agency",
-      message-version: "1.0.0",
-      message: {
-        DOI: "10.1037/0003-066x.59.1.29",
-        agency: {
-          id: "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.
-
-## Results Overview
-
-All results are returned in JSON. There are two general types of results:
-
-- Singletons
-- Lists
-
-The mime-type for API results is `application/vnd.crossref-api-message+json` 
-
-
-### Singletons
-
-Singletons are single results. Retrieving metadata for a specific identifier (e.g. DOI, ISSN, funder_identifier) typically returns in a singleton result.
-
-### Lists
-Lists results can contain multiple entries. Searching or filtering typically returns a list result. A list has two parts:
-
-- Summary, which include the following information:
-    - status (e.g. "ok", error)
-    - message-type (e.g. "work-list" )
-    - message-version (e.g. 1.0.0 )
-- Items, which will will contain the items matching the query or filter. 
-
-Note that the "message-type" returned will differ from the mime-type:
-
-- funder (singleton)
-- prefix (singleton)
-- member (singleton)
-- work (singleton)
-- work-list (list)
-- funder-list (list)
-- prefix-list (list)
-- member-list (list)
-
-Normally, an API list result will return both the summary and the items. If you want to just retrieve the summary, you can do so by specifying that the number of rows returned should be zero. 
-### Sort order
-
-If the API call includes a query, then the sort order will be by the relevance score. If no query is included, then the sort order will be by DOI update date.
-
-
-## Resource Components
-Major resource components supported by the CrossRef API are:
-
-- works
-- funders
-- members
-- prefixes
-- types
-- journals
-
-These can be used alone like this
-
-| resource      | description                       |
-|:--------------|:----------------------------------|
-| `/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) |
-| `/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 |
-
-
-### 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. |
-| `/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 |
-| `/types/{type_id}` | returns information about a metadata work type |
-| `/journals/{issn}` | returns information about a journal with the given ISSN |
-
-### Combining resource components
-
-The works component can be appended to other resources.
-
-| resource                    | description                       |
-|:----------------------------|:----------------------------------|
-| `/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) |
-| `/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.
-
-| parameter                    | description                 |
-|:-----------------------------|:----------------------------|
-| `query`                      | limited [DisMax](https://wiki.apache.org/solr/DisMax) query terms |
-| `filter={filter_name}:{value}`| filter results by specific fields |
-| `rows={#}`                   | results per per page | 
-| `offset={#}`                 | result offset |                         
-| `sample={#}`                 | return random N results |
-| `sort={#}`                   | sort results by a certain field |
-| `order={#}`                  | set the sort order to `asc` or `desc` |
-| `facet=t`                    | enable facet information in responses |
-
-Multiple filters can be specified by separating name:value pairs with a comma:
-
-    http://api.crossref.org/works?filter=has-orcid:true,from-pub-date:2004-04-04
-
-### Example query using URI parameters
-
-    http://api.crossref.org/funders/100000015/works?query=global+state&filter=has-orcid:true&rows=1
-
-### Example query using JSON in body of GET request
-
-Note that if you include a body in your `GET` request, any URI parameters will be ignored. In short, you cannot mix URI parameters and JSON queries.
-
-To use the API using JSON, pass the JSON in the body of the HTTP GET request like this:
-
-    curl -X GET -H "Content-Type: application/json" -d '{"query": "psychoceramics", "offset": 40, "rows": 20, "filter": {"has-orcid": true, "publisher": "10.5555"}}'  http://api.crossref.org/works
-
-## Queries
-
-Queries support a subset of [DisMax](https://wiki.apache.org/solr/DisMax), so, for example you can refine queries as follows.
-
-**Works that include "renear" but not "ontologies"**
-
-    http://api.crossref.org/works?query=renear+-ontologies
-    
-or using JSON
-
-    curl -X GET -H "Content-Type: application/json" -d '{"query": "renear -ontologies"}'  http://api.crossref.org/works
-
-## Sorting
-
-Results from a listy response can be sorted by applying the `sort` and `order` parameters. Order
-sets the result ordering, either `asc` or `desc`. Sort sets the field by which results will be
-sorted. Possible values are:
-
-| Sort value | Description |
-|------------|-------------|
-| `score` or `relevance` | Sort by relevance score |
-| `updated` | Sort by date of most recent change to metadata. Currently the same as `deposited`. |
-| `deposited` | Sort by time of most recent deposit |
-| `indexed` | Sort by time of most recent index |
-| `published` | Sort by publication date |
-
-An example that sorts results in order of publication, beginning with the least recent:
-
-    http://api.crossref.org/works?query=josiah+carberry&sort=published&order=asc
-
-## Facet Counts
-
-Facet counts can be retrieved by enabling faceting; `facet=t` (or `1`, `true`). Facet counts
-give counts per field value for an entire result set.
-
-## Filter Names
-
-Filters allow you to narrow queries. All filter results are lists.  The following filters are supported:
-
-| filter     | possible values | description|
-|:-----------|:----------------|:-----------|
-| `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 |
-| `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}` |
-| `until-deposit-date` | `{date}` | metadata last (re)deposited before (inclusive) `{date}` |
-| `from-update-date` | `{date}` | Metadata updated since (inclusive) `{date}`. Currently the same as `from-deposit-date`. |
-| `until-update-date` | `{date}` | Metadata updated before (inclusive) `{date}`. Currently the same as `until-deposit-date`. |
-| `from-first-deposit-date` | `{date}` | metadata first deposited since (inclusive) `{date}` [^*] |
-| `until-first-deposit-date` | `{date}` | metadata first deposited before (inclusive) `{date}` [^*] |
-| `from-pub-date` | `{date}` | metadata where published date is since (inclusive) `{date}` |
-| `until-pub-date` | `{date}` | metadata where published date is before (inclusive)  `{date}` |
-| `has-license` | | metadata that includes any `` elements. |
-| `license.url` | `{url}` | metadata where `` value equals `{url}` |
-| `license.version` | `{string}` | metadata where the ``'s `applies_to` attribute  is `{string}`|
-| `license.delay` | `{integer}` | metadata where difference between publication date and the ``'s `start_date` attribute is <= `{integer}` (in days)|
-| `has-full-text` |  | metadata that includes any full text `` elements. |
-| `full-text.version` | `{string}`  | metadata where `` element's `content_version` attribute is `{string}`. |
-| `full-text.type` | `{mime_type}`  | metadata where `` element's `content_type` attribute is `{mime_type}` (e.g. `application/pdf`). |
-| `public-references` | | metadata where publishers allow references to be distributed publically. [^*] |
-| `has-references` | | metadata for works that have a list of references |
-| `has-archive` | | metadata which include name of archive partner |
-| `archive` | `{string}` | metadata which where value of archive partner is `{string}` |
-| `has-orcid` | | metadata which includes one or more ORCIDs |
-| `orcid` | `{orcid}` | metadata where `` element's value = `{orcid}` |
-| `issn` | `{issn}` | metadata where record has an ISSN = `{issn}`. Format is `xxxx-xxxx`. |
-| `type` | `{type}` | metadata records whose type = `{type}`. Type must be an ID value from the list of types returned by the `/types` resource |
-| `directory` | `{directory}` | metadata records whose article or serial are mentioned in the given `{directory}`. Currently the only supported value is `doaj`. |
-| `doi` | `{doi}` | metadata describing the DOI `{doi}` |
-| `updates` | `{doi}` | metadata for records that represent editorial updates to the DOI `{doi}` |
-| `is-update` | | metadata for records that represent editorial updates |
-| `has-update-policy` | | metadata for records that include a link to an editorial update policy |
-| `container-title` | | metadata for records with a publication title exactly with an exact match |
-| `publisher-name` | | metadata for records with an exact matching publisher name |
-| `category-name` | | metadata for records with an exact matching category label |
-| `type-name` | | metadata for records with an exacty matching type label |
-| `award.number` | `{award_number}` | metadata for records with a matching award nunber. Optionally combine with `award.funder` |
-| `award.funder` | `{funder doi or id}` | metadata for records with an award with matching funder. Optionally combine with `award.number` |
-
-[^*]: Not implemented yet.
-
-### 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. 
-
-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. 
-
-### Notes on incremental metadata updates
-
-When using time filters to retrieve periodic, incremental metadata updates,
-the `from-index-date` filter should be used over `from-update-date`,
-`from-deposit-date`, `from-first-deposit-date` and `from-pub-date`. The
-timestamp that `from-index-date` filters on is guaranteed to be updated
-every time there is a change to metadata requiring a reindex.
-
-## Result controls
-
-You can control the delivery and selection  results using the `rows`, `offset` and `sample` parameters. 
-
-### Rows 
-
-Normally, results are returned 20 at a time. You can control the number of results returns by using the `rows` parameter. To limit results to 5, for example, you could do the following:
-
-    http://api.crossref.org/works?query=allen+renear&rows=5
-
-If you would just like to get the `summary` of the results, you can set the rows to 0 (zero).
-
-    http://api.crossref.org/works?query=allen+renear&rows=0
-    
-The maximum number rows you can ask for in one query is `1000`.
-
-### Offset
-
-The number of returned items is controlled by the `rows` parameter, but you can select the offset into the result list by using the `offset` parameter.  So, for example, to select the second set of 5 results (i.e. results 6 through 10), you would do the following:
-
-    http://api.crossref.org/works?query=allen+renear&rows=5&offset=5
-    
-### Sample
-
-Being able to select random results is useful for both testing and sampling. You can use the `sample` parameter to retrieve random results. So, for example, the following select 10 random works:
-
-    http://api.crossref.org/works?sample=10
-    
-Note that when you use the `sample` parameter, the `rows` and `offset` parameters are ignored.
-
-
-### Example Queries
-
-**All works published by owner prefix `10.1016` in January 2010**
-
-    http://api.crossref.org/prefixes/10.1016/works?filter=from-pub-date:2010-01,until-pub-date:2010-01
-
-**All works funded by `10.13039/100000001` that have a CC-BY license**
-
-    http://api.crossref.org/funders/10.13039/100000001/works?filter=license.url:http://creativecommons.org/licenses/by/3.0/deed.en_US
-
-**All works published by owner prefix 10.5555 from February 2010 to February 2013 that have a CC-BY license**
-
-    http://api.crossref.org/prefixes/10.5555/works?filter=license.url:http://creativecommons.org/licenses/by/3.0/deed.en_US,from-pub-date:2010-02,until-pub-date:2013-02
-
-**All works funded by `10.13039/100000015` where license = CC-BY and embargo <= 365 days**
-
-    http://api.crossref.org/funders/10.13039/100000015/works?filter=license.url:http://creativecommons.org/licenses/by/3.0/deed.en_US,license.delay:365
-
-Note that the filters for license URL and maximum license embargo period (license.url and license.delay) combine to filter each document's metadata for a license with both of these properties.
-
-**All works where the archive partner listed = 'LOCKSS'**
-
-    http://api.crossref.org/works?filter?archive=LOCKSS
-    
-**All members with `hind` in their name (e.g. Hindawi)**
-
-    http://api.crossref.org/members?query=hind
-    
-**All licenses linked to works published by Elsevier**
-
-    http://api.crossref.org/licenses?filter=member:78
-    
-**All licenses applied to works published in the journal `Pathology Research International`**
-
-    http://api.crossref.org/licenses?filter=issn:2090-8091
-    
-**All works with an award numbered roughly `1 F31 MH11745` also awarded by funder with ID `10.13039/100000025`:
-
-    http://api.crossref.org/works?filter=award.number:1F31MH11745,award.funder:10.13039/100000025
-
-## Versioning
-
-In theory, the syntax of the API can vary independently of the result representations. In practice, major version changes in either will require changes to API clients and so versioning of the API will apply to both the API syntax and the result representation.
-
-The API uses a semantic versioning scheme whereby the version number is divided into three parts delimited by periods. The first number represents the "major" release number. The second represents a "minor" release number and the third represents an "internal" release number.  
-      
-    Version 1.20.31
-            ^  ^  ^
-            |  |  |
-        major  |  |
-           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. 
-
-**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.
-
-Adding syntax options or metadata to representations will normally be backwards compatible and will thus normally only trigger minor version changes. Renaming or restructuring syntax options of metadata tends not to be backward compatible and will thus typically trigger major version changes
-
-### How to manage API versions
-
-If you need to tie your implementation to a specific major version of the API, you can do so by using content-negotiation and specifying the version of the API in the `ACCEPT` header as follows:
-
-     application/vnd.crossref-api-message+json; version=1.0
-
-Minor version numbers will be ignored in `ACCEPT` headers as they are by definition backwards compatible.
-
-If you omit a specific version in your `ACCEPT` header, the system will default to using the latest version of the API. 
-
-Note that requesting a version of the API via content type is not yet supported.
-
-## Error messages
-
-There will be no errors, and therefor error messages will be unnecessary. But seriously… coming soon.
+The canonical URL for this documentation is http://api.crossref.org . Please update your bookmarks.
diff --git a/rest_api.md b/rest_api.md
new file mode 100644
index 0000000..8ab1797
--- /dev/null
+++ b/rest_api.md
@@ -0,0 +1,399 @@
+# CrossRef REST API
+
+## Version History
+
+- V1: 2013-09-08, first draft.
+- V2: 2013-09-24, reference platform deployed
+- v3: 2013-09-25, reworked filters. Added API versioning doc 
+- v4: 2013-09-25, more filter changes.
+- v5: 2013-09-27, doc mime-type and message-type relationship
+- v6: 2013-10-01, updated `sample` & added examples with filters
+- v6: 2013-10-01, corrected warning date
+- v7: 2013-10-02, fixed typos
+- v8: 2013-10-17, updated warning. Added email address
+- v9: 2013-12-13, update example urls
+- v10: 2013-12-13, /types routes, type filter, issn filter
+- v11: 2013-12-14, indexed timestamps, has-archive and archive implemented
+- v12: 2014-01-06, directory filter
+- v13: 2014-02-10, new `/members`, `/publishers` becomes `/prefixes`, new `member` filter, `publisher` filter becomes `prefix`
+- v14: 2014-02-14, new `has-funder` filter.
+- v15: 2014-02-27, new `/licenses` route
+- v16: 2014-05-19, new `/journals` route, new CrossMark (updates and update policy) filters, new `sort` and `order` parameters
+- v17: 2014-05-19, new `facet` query parameter
+- v18: 2014-05-29, new `/works/{doi}/agency` route
+- v19: 2014-06-23, new textual filters - `container-title`, `publisher-name`, `category-name`.
+- v20: 2014-06-24, OR filter queries, `type-name` filter.
+- 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. 
+
+## Background
+
+See the document, [CrossRef metadata best practice to support key performance indicators (KPIs) for funding agencies](http://api.crossref.org/docs/funder_kpi_metadata_best_practice.html), for background.
+
+## Warning
+
+The API described here is in alpha. If you encounter problems with the API or the documentation, please report them to:
+
+![](http://labs.crossref.org/wp-content/uploads/2013/01/labs_email.png)
+
+
+## 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:
+
+`http://api.crossref.org/works/{doi}/agency`
+
+Testing the following CrossRef DOI:
+
+`10.1037/0003-066X.59.1.29`
+
+Using the URL:
+
+`http://api.crossref.org/works/10.1037/0003-066X.59.1.29/agency`
+
+Will return the following result:
+
+    {
+      status: "ok",
+      message-type: "work-agency",
+      message-version: "1.0.0",
+      message: {
+        DOI: "10.1037/0003-066x.59.1.29",
+        agency: {
+          id: "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.
+
+## Results Overview
+
+All results are returned in JSON. There are two general types of results:
+
+- Singletons
+- Lists
+
+The mime-type for API results is `application/vnd.crossref-api-message+json` 
+
+
+### Singletons
+
+Singletons are single results. Retrieving metadata for a specific identifier (e.g. DOI, ISSN, funder_identifier) typically returns in a singleton result.
+
+### Lists
+Lists results can contain multiple entries. Searching or filtering typically returns a list result. A list has two parts:
+
+- Summary, which include the following information:
+    - status (e.g. "ok", error)
+    - message-type (e.g. "work-list" )
+    - message-version (e.g. 1.0.0 )
+- Items, which will will contain the items matching the query or filter. 
+
+Note that the "message-type" returned will differ from the mime-type:
+
+- funder (singleton)
+- prefix (singleton)
+- member (singleton)
+- work (singleton)
+- work-list (list)
+- funder-list (list)
+- prefix-list (list)
+- member-list (list)
+
+Normally, an API list result will return both the summary and the items. If you want to just retrieve the summary, you can do so by specifying that the number of rows returned should be zero. 
+### Sort order
+
+If the API call includes a query, then the sort order will be by the relevance score. If no query is included, then the sort order will be by DOI update date.
+
+
+## Resource Components
+Major resource components supported by the CrossRef API are:
+
+- works
+- funders
+- members
+- prefixes
+- types
+- journals
+
+These can be used alone like this
+
+| resource      | description                       |
+|:--------------|:----------------------------------|
+| `/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) |
+| `/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 |
+
+
+### 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. |
+| `/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 |
+| `/types/{type_id}` | returns information about a metadata work type |
+| `/journals/{issn}` | returns information about a journal with the given ISSN |
+
+### Combining resource components
+
+The works component can be appended to other resources.
+
+| resource                    | description                       |
+|:----------------------------|:----------------------------------|
+| `/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) |
+| `/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.
+
+| parameter                    | description                 |
+|:-----------------------------|:----------------------------|
+| `query`                      | limited [DisMax](https://wiki.apache.org/solr/DisMax) query terms |
+| `filter={filter_name}:{value}`| filter results by specific fields |
+| `rows={#}`                   | results per per page | 
+| `offset={#}`                 | result offset |                         
+| `sample={#}`                 | return random N results |
+| `sort={#}`                   | sort results by a certain field |
+| `order={#}`                  | set the sort order to `asc` or `desc` |
+| `facet=t`                    | enable facet information in responses |
+
+Multiple filters can be specified by separating name:value pairs with a comma:
+
+    http://api.crossref.org/works?filter=has-orcid:true,from-pub-date:2004-04-04
+
+### Example query using URI parameters
+
+    http://api.crossref.org/funders/100000015/works?query=global+state&filter=has-orcid:true&rows=1
+
+### Example query using JSON in body of GET request
+
+Note that if you include a body in your `GET` request, any URI parameters will be ignored. In short, you cannot mix URI parameters and JSON queries.
+
+To use the API using JSON, pass the JSON in the body of the HTTP GET request like this:
+
+    curl -X GET -H "Content-Type: application/json" -d '{"query": "psychoceramics", "offset": 40, "rows": 20, "filter": {"has-orcid": true, "publisher": "10.5555"}}'  http://api.crossref.org/works
+
+## Queries
+
+Queries support a subset of [DisMax](https://wiki.apache.org/solr/DisMax), so, for example you can refine queries as follows.
+
+**Works that include "renear" but not "ontologies"**
+
+    http://api.crossref.org/works?query=renear+-ontologies
+    
+or using JSON
+
+    curl -X GET -H "Content-Type: application/json" -d '{"query": "renear -ontologies"}'  http://api.crossref.org/works
+
+## Sorting
+
+Results from a listy response can be sorted by applying the `sort` and `order` parameters. Order
+sets the result ordering, either `asc` or `desc`. Sort sets the field by which results will be
+sorted. Possible values are:
+
+| Sort value | Description |
+|------------|-------------|
+| `score` or `relevance` | Sort by relevance score |
+| `updated` | Sort by date of most recent change to metadata. Currently the same as `deposited`. |
+| `deposited` | Sort by time of most recent deposit |
+| `indexed` | Sort by time of most recent index |
+| `published` | Sort by publication date |
+
+An example that sorts results in order of publication, beginning with the least recent:
+
+    http://api.crossref.org/works?query=josiah+carberry&sort=published&order=asc
+
+## Facet Counts
+
+Facet counts can be retrieved by enabling faceting; `facet=t` (or `1`, `true`). Facet counts
+give counts per field value for an entire result set.
+
+## Filter Names
+
+Filters allow you to narrow queries. All filter results are lists.  The following filters are supported:
+
+| filter     | possible values | description|
+|:-----------|:----------------|:-----------|
+| `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 |
+| `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}` |
+| `until-deposit-date` | `{date}` | metadata last (re)deposited before (inclusive) `{date}` |
+| `from-update-date` | `{date}` | Metadata updated since (inclusive) `{date}`. Currently the same as `from-deposit-date`. |
+| `until-update-date` | `{date}` | Metadata updated before (inclusive) `{date}`. Currently the same as `until-deposit-date`. |
+| `from-first-deposit-date` | `{date}` | metadata first deposited since (inclusive) `{date}` [^*] |
+| `until-first-deposit-date` | `{date}` | metadata first deposited before (inclusive) `{date}` [^*] |
+| `from-pub-date` | `{date}` | metadata where published date is since (inclusive) `{date}` |
+| `until-pub-date` | `{date}` | metadata where published date is before (inclusive)  `{date}` |
+| `has-license` | | metadata that includes any `` elements. |
+| `license.url` | `{url}` | metadata where `` value equals `{url}` |
+| `license.version` | `{string}` | metadata where the ``'s `applies_to` attribute  is `{string}`|
+| `license.delay` | `{integer}` | metadata where difference between publication date and the ``'s `start_date` attribute is <= `{integer}` (in days)|
+| `has-full-text` |  | metadata that includes any full text `` elements. |
+| `full-text.version` | `{string}`  | metadata where `` element's `content_version` attribute is `{string}`. |
+| `full-text.type` | `{mime_type}`  | metadata where `` element's `content_type` attribute is `{mime_type}` (e.g. `application/pdf`). |
+| `public-references` | | metadata where publishers allow references to be distributed publically. [^*] |
+| `has-references` | | metadata for works that have a list of references |
+| `has-archive` | | metadata which include name of archive partner |
+| `archive` | `{string}` | metadata which where value of archive partner is `{string}` |
+| `has-orcid` | | metadata which includes one or more ORCIDs |
+| `orcid` | `{orcid}` | metadata where `` element's value = `{orcid}` |
+| `issn` | `{issn}` | metadata where record has an ISSN = `{issn}`. Format is `xxxx-xxxx`. |
+| `type` | `{type}` | metadata records whose type = `{type}`. Type must be an ID value from the list of types returned by the `/types` resource |
+| `directory` | `{directory}` | metadata records whose article or serial are mentioned in the given `{directory}`. Currently the only supported value is `doaj`. |
+| `doi` | `{doi}` | metadata describing the DOI `{doi}` |
+| `updates` | `{doi}` | metadata for records that represent editorial updates to the DOI `{doi}` |
+| `is-update` | | metadata for records that represent editorial updates |
+| `has-update-policy` | | metadata for records that include a link to an editorial update policy |
+| `container-title` | | metadata for records with a publication title exactly with an exact match |
+| `publisher-name` | | metadata for records with an exact matching publisher name |
+| `category-name` | | metadata for records with an exact matching category label |
+| `type-name` | | metadata for records with an exacty matching type label |
+| `award.number` | `{award_number}` | metadata for records with a matching award nunber. Optionally combine with `award.funder` |
+| `award.funder` | `{funder doi or id}` | metadata for records with an award with matching funder. Optionally combine with `award.number` |
+
+[^*]: Not implemented yet.
+
+### 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. 
+
+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. 
+
+### Notes on incremental metadata updates
+
+When using time filters to retrieve periodic, incremental metadata updates,
+the `from-index-date` filter should be used over `from-update-date`,
+`from-deposit-date`, `from-first-deposit-date` and `from-pub-date`. The
+timestamp that `from-index-date` filters on is guaranteed to be updated
+every time there is a change to metadata requiring a reindex.
+
+## Result controls
+
+You can control the delivery and selection  results using the `rows`, `offset` and `sample` parameters. 
+
+### Rows 
+
+Normally, results are returned 20 at a time. You can control the number of results returns by using the `rows` parameter. To limit results to 5, for example, you could do the following:
+
+    http://api.crossref.org/works?query=allen+renear&rows=5
+
+If you would just like to get the `summary` of the results, you can set the rows to 0 (zero).
+
+    http://api.crossref.org/works?query=allen+renear&rows=0
+    
+The maximum number rows you can ask for in one query is `1000`.
+
+### Offset
+
+The number of returned items is controlled by the `rows` parameter, but you can select the offset into the result list by using the `offset` parameter.  So, for example, to select the second set of 5 results (i.e. results 6 through 10), you would do the following:
+
+    http://api.crossref.org/works?query=allen+renear&rows=5&offset=5
+    
+### Sample
+
+Being able to select random results is useful for both testing and sampling. You can use the `sample` parameter to retrieve random results. So, for example, the following select 10 random works:
+
+    http://api.crossref.org/works?sample=10
+    
+Note that when you use the `sample` parameter, the `rows` and `offset` parameters are ignored.
+
+
+### Example Queries
+
+**All works published by owner prefix `10.1016` in January 2010**
+
+    http://api.crossref.org/prefixes/10.1016/works?filter=from-pub-date:2010-01,until-pub-date:2010-01
+
+**All works funded by `10.13039/100000001` that have a CC-BY license**
+
+    http://api.crossref.org/funders/10.13039/100000001/works?filter=license.url:http://creativecommons.org/licenses/by/3.0/deed.en_US
+
+**All works published by owner prefix 10.5555 from February 2010 to February 2013 that have a CC-BY license**
+
+    http://api.crossref.org/prefixes/10.5555/works?filter=license.url:http://creativecommons.org/licenses/by/3.0/deed.en_US,from-pub-date:2010-02,until-pub-date:2013-02
+
+**All works funded by `10.13039/100000015` where license = CC-BY and embargo <= 365 days**
+
+    http://api.crossref.org/funders/10.13039/100000015/works?filter=license.url:http://creativecommons.org/licenses/by/3.0/deed.en_US,license.delay:365
+
+Note that the filters for license URL and maximum license embargo period (license.url and license.delay) combine to filter each document's metadata for a license with both of these properties.
+
+**All works where the archive partner listed = 'LOCKSS'**
+
+    http://api.crossref.org/works?filter?archive=LOCKSS
+    
+**All members with `hind` in their name (e.g. Hindawi)**
+
+    http://api.crossref.org/members?query=hind
+    
+**All licenses linked to works published by Elsevier**
+
+    http://api.crossref.org/licenses?filter=member:78
+    
+**All licenses applied to works published in the journal `Pathology Research International`**
+
+    http://api.crossref.org/licenses?filter=issn:2090-8091
+    
+**All works with an award numbered roughly `1 F31 MH11745` also awarded by funder with ID `10.13039/100000025`:
+
+    http://api.crossref.org/works?filter=award.number:1F31MH11745,award.funder:10.13039/100000025
+
+## Versioning
+
+In theory, the syntax of the API can vary independently of the result representations. In practice, major version changes in either will require changes to API clients and so versioning of the API will apply to both the API syntax and the result representation.
+
+The API uses a semantic versioning scheme whereby the version number is divided into three parts delimited by periods. The first number represents the "major" release number. The second represents a "minor" release number and the third represents an "internal" release number.  
+      
+    Version 1.20.31
+            ^  ^  ^
+            |  |  |
+        major  |  |
+           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. 
+
+**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.
+
+Adding syntax options or metadata to representations will normally be backwards compatible and will thus normally only trigger minor version changes. Renaming or restructuring syntax options of metadata tends not to be backward compatible and will thus typically trigger major version changes
+
+### How to manage API versions
+
+If you need to tie your implementation to a specific major version of the API, you can do so by using content-negotiation and specifying the version of the API in the `ACCEPT` header as follows:
+
+     application/vnd.crossref-api-message+json; version=1.0
+
+Minor version numbers will be ignored in `ACCEPT` headers as they are by definition backwards compatible.
+
+If you omit a specific version in your `ACCEPT` header, the system will default to using the latest version of the API. 
+
+Note that requesting a version of the API via content type is not yet supported.
+
+## Error messages
+
+There will be no errors, and therefor error messages will be unnecessary. But seriously… coming soon.

From 53498e64c8c283515c4e326b21a94bb6014ee550 Mon Sep 17 00:00:00 2001
From: Karl Jonathan Ward 
Date: Mon, 1 Sep 2014 10:49:07 +0100
Subject: [PATCH 072/219] Mention multiple filters and dot filters

Resolves #2.
---
 rest_api.md | 22 ++++++++++++++++++++++
 1 file changed, 22 insertions(+)

diff --git a/rest_api.md b/rest_api.md
index 8ab1797..b132643 100644
--- a/rest_api.md
+++ b/rest_api.md
@@ -25,6 +25,7 @@
 - v20: 2014-06-24, OR filter queries, `type-name` filter.
 - 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
 
 ## Background
 
@@ -272,6 +273,27 @@ Filters allow you to narrow queries. All filter results are lists.  The followin
 
 [^*]: Not implemented yet.
 
+### Multiple filters
+
+Multiple filters can be specified in a single query. In such a case, different filters will be applied with AND semantics, while specifying the same filter multiple times will result in OR semantics - that is, specifying the filters:
+
+- `is-update:true`
+- `from-pub-date:2014-03-03`
+- `award.funder:10.13039/100000001`
+- `award.funder:10.13039/100000050`
+
+would locate documents that are updates, were published on or after 3rd March 2014 and were funded by either the National Science Foundation (`10.13039/100000001`) or the National Heart, Lung, and Blood Institute (`10.13039/100000050`). These filters would be specified by joining each filter together with a comma:
+
+    /works?filter=is-update:true,from-pub-date:2014-03-03,award.funder:10.13039/100000001,award.funder:10.13039/100000050
+    
+### Dot filters
+
+A filter with a dot in its name is special. The dot signifies that the filter will be applied to some other record type that is related to primary resource record type. For example, with work queries, one can filter on works that have an award, where the same award has a particular award number and award-gving funding agency:
+
+    /works?filter=award.number:CBET-0756451,award.doi:10.13039/100000001
+    
+Here we filter on works that have an award by the National Science Foundation that also has the award number `CBET-0756451`.
+
 ### 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. 

From 53d8ffb0d8be923302bf42935522e66c52d50024 Mon Sep 17 00:00:00 2001
From: Karl Jonathan Ward 
Date: Mon, 1 Sep 2014 10:55:19 +0100
Subject: [PATCH 073/219] Fix misplaced character in version history

---
 rest_api.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/rest_api.md b/rest_api.md
index b132643..d411dae 100644
--- a/rest_api.md
+++ b/rest_api.md
@@ -25,7 +25,7 @@
 - v20: 2014-06-24, OR filter queries, `type-name` filter.
 - 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
+- v23, 2014-09-01, semantics of mutliple filters, dot filters
 
 ## Background
 

From c6a59ae925aaac8a5b33d6d37837a9d0a25c7522 Mon Sep 17 00:00:00 2001
From: Karl Jonathan Ward 
Date: Mon, 1 Sep 2014 10:59:14 +0100
Subject: [PATCH 074/219] Correct award.funder filter name in example

---
 rest_api.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/rest_api.md b/rest_api.md
index d411dae..17893ec 100644
--- a/rest_api.md
+++ b/rest_api.md
@@ -290,7 +290,7 @@ would locate documents that are updates, were published on or after 3rd March 20
 
 A filter with a dot in its name is special. The dot signifies that the filter will be applied to some other record type that is related to primary resource record type. For example, with work queries, one can filter on works that have an award, where the same award has a particular award number and award-gving funding agency:
 
-    /works?filter=award.number:CBET-0756451,award.doi:10.13039/100000001
+    /works?filter=award.number:CBET-0756451,award.funder:10.13039/100000001
     
 Here we filter on works that have an award by the National Science Foundation that also has the award number `CBET-0756451`.
 

From c458a18f366cc5c2993b36c7a4d40d224a19adc1 Mon Sep 17 00:00:00 2001
From: Karl Jonathan Ward 
Date: Mon, 1 Sep 2014 17:35:29 +0100
Subject: [PATCH 075/219] Use funder instead of award.funder in an example

---
 rest_api.md | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/rest_api.md b/rest_api.md
index 17893ec..987d0bd 100644
--- a/rest_api.md
+++ b/rest_api.md
@@ -279,12 +279,12 @@ Multiple filters can be specified in a single query. In such a case, different f
 
 - `is-update:true`
 - `from-pub-date:2014-03-03`
-- `award.funder:10.13039/100000001`
-- `award.funder:10.13039/100000050`
+- `funder:10.13039/100000001`
+- `funder:10.13039/100000050`
 
 would locate documents that are updates, were published on or after 3rd March 2014 and were funded by either the National Science Foundation (`10.13039/100000001`) or the National Heart, Lung, and Blood Institute (`10.13039/100000050`). These filters would be specified by joining each filter together with a comma:
 
-    /works?filter=is-update:true,from-pub-date:2014-03-03,award.funder:10.13039/100000001,award.funder:10.13039/100000050
+    /works?filter=is-update:true,from-pub-date:2014-03-03,funder:10.13039/100000001,funder:10.13039/100000050
     
 ### Dot filters
 

From 57b09dacf34dddc6e243a5da9f95b4bd341dc3fe Mon Sep 17 00:00:00 2001
From: Geoffrey Bilder 
Date: Wed, 15 Oct 2014 08:22:44 +0100
Subject: [PATCH 076/219] Update rest_api.md

Added info on license of CrossRef metadata itself. Doh.
---
 rest_api.md | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/rest_api.md b/rest_api.md
index 987d0bd..6c56c71 100644
--- a/rest_api.md
+++ b/rest_api.md
@@ -26,6 +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.
 
 ## Background
 
@@ -37,6 +38,9 @@ The API described here is in alpha. If you encounter problems with the API or th
 
 ![](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/).
 
 ## Overview
 

From 0fe9c67949fd6fd83064f819d6dacbcc68416574 Mon Sep 17 00:00:00 2001
From: Geoffrey Bilder 
Date: Tue, 11 Nov 2014 10:49:55 +0000
Subject: [PATCH 077/219] updated tour

---
 rest_api_tour.md | 24 ++++++++++++++++++++++++
 1 file changed, 24 insertions(+)

diff --git a/rest_api_tour.md b/rest_api_tour.md
index 26b0f35..31495a9 100644
--- a/rest_api_tour.md
+++ b/rest_api_tour.md
@@ -92,8 +92,32 @@ Ok, lets see how many records with the word "blood" in the metadata have license
 
 Let's download the results and download the content locally to TDM
 
+We could just get them all:
+
     http://api.crossref.org/works?filter=has-license:true,has-full-text:true&query=blood&rows=884
 
+But for the purposes of this demo, let's subdivide them by publisher.
+
+
+First let's get a sample of Elsevier titles:
+
+What is Elsevier's CrossRef member id number? 
+
+    http://api.crossref.org/members?query=elsevier
+
+Now what DOIs do  Elsevier have that match our criteria?
+
+    http://api.crossref.org/members/78/works?filter=has-license:true,has-full-text:true&query=blood&rows=50
+
+Now what is Hindawi's CrossRef member id number?
+
+    http://api.crossref.org/members?query=elsevier
+
+Now lets get some Hindawi articles that match the criteria:
+
+    http://api.crossref.org/members/98/works?filter=has-license:true,has-full-text:true&query=blood&rows=50
+
+
 
 
 ## Other examples

From 034959d053bc3b528233d63ad766dc258f4e87d8 Mon Sep 17 00:00:00 2001
From: Geoffrey Bilder 
Date: Tue, 11 Nov 2014 11:58:44 +0000
Subject: [PATCH 078/219] changes for CR workshop

---
 .DS_Store        | Bin 0 -> 6148 bytes
 rest_api_tour.md |   7 +++----
 2 files changed, 3 insertions(+), 4 deletions(-)
 create mode 100644 .DS_Store

diff --git a/.DS_Store b/.DS_Store
new file mode 100644
index 0000000000000000000000000000000000000000..36d5c4853795d5a2bf7f8c8998820f442b644998
GIT binary patch
literal 6148
zcmeH~&u$Yj5XL{39HLfKDdNBhtpo=yAfV#FZ50&+S2%HD+5CYpTj*5v{ab0FiI&ulG}Gwyv>Fbk)qweSSiGb>xb#9x
zx{ZxFyZ;oOuk8OqU$g?}`cAv#JeaiF`MF`|FrFU2yjqBE;Ioi@P?kg;u?eJ@vtNZP>SXjmgTfSDGx4Qnlzv;v60=^&W
zIT^OxJ=HTE>oGmA;Qt-#JyyTTyyJUp#JP`+A)f3Tu$|GeGRsy&hd{4QxU)^V2LV%^
z7)T5x2L3Q$=R-y@%plnCiqpVxY;ujqtN)_y3FC@BgM!`jr?+4E$FN
zxX#JjlRhEEyLBr#yK6Jb2a1W!TL<(iRPj3Y4ZDi(P`ogfSp&=?t^?A8q(1_lhEyd6
Hu9bmb@w@P2

literal 0
HcmV?d00001

diff --git a/rest_api_tour.md b/rest_api_tour.md
index 31495a9..5af10c0 100644
--- a/rest_api_tour.md
+++ b/rest_api_tour.md
@@ -3,6 +3,7 @@
 ## Version History
 
 - V1: 2014-04-18, first draft.
+- V2:2014-11-10, edits for CR workshop 
 
 ## Overview
 
@@ -12,10 +13,8 @@ The following short examples show how the CrossRef REST APIs can be used to prov
 
 In many cases, you can simply paste the example URIs into a browser's URL box, but if you want to see the resulting JSON formatted correctly, then we recommend that you install one of the following plugins:
 
-- Firefox Users:
-- Chrome Users:
-
-Some of the demonstrations here require the use of content negotiation. This is difficult to demonstrate in a browser unless you use a special plugin. Accordingly, the URIs for this demo have also been included as a project for the XXXX plugin available for Chrome.
+- Firefox Users: [JSONView](http://jsonview.com/)
+- Chrome Users: [JSONView](https://chrome.google.com/webstore/detail/jsonview/chklaanhfefbnpoihckbnefhakgolnmc)
 
 ## A fake problem
 

From b6864eb8582f7250c12bcab547aa3e37f056af8d Mon Sep 17 00:00:00 2001
From: Geoffrey Bilder 
Date: Tue, 11 Nov 2014 11:59:55 +0000
Subject: [PATCH 079/219] changes for CR workshop

---
 rest_api_tour.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/rest_api_tour.md b/rest_api_tour.md
index 5af10c0..cbdfd38 100644
--- a/rest_api_tour.md
+++ b/rest_api_tour.md
@@ -3,7 +3,7 @@
 ## Version History
 
 - V1: 2014-04-18, first draft.
-- V2:2014-11-10, edits for CR workshop 
+- V2: 2014-11-10, edits for CR workshop 
 
 ## Overview
 

From 61f1e0dc5762cb8a720c676a9ea873ec979e5633 Mon Sep 17 00:00:00 2001
From: Karl Jonathan Ward 
Date: Thu, 15 Jan 2015 11:58:47 +0000
Subject: [PATCH 080/219] Mention application/pdf type

---
 deposit_api.md | 1 +
 1 file changed, 1 insertion(+)

diff --git a/deposit_api.md b/deposit_api.md
index dc96e55..77fcef5 100644
--- a/deposit_api.md
+++ b/deposit_api.md
@@ -87,6 +87,7 @@ one of:
 |--------------|-------------|
 | application/vnd.crossref.deposit+xml | [Full deposit](http://doi.crossref.org/schemas/crossref4.3.4.xsd) |
 | application/vnd.crossref.partial+xml | [Partial (resource) deposit](http://doi.crossref.org/schemas/doi_resources4.3.2.xsd) |
+| application/pdf | PDF deposit for citation extraction |
 
 ### Specifying a Ping Back URL
 

From 3f1d89fc33ad0790d38e879a8121543fe862c7bf Mon Sep 17 00:00:00 2001
From: Karl Jonathan Ward 
Date: Thu, 15 Jan 2015 12:00:41 +0000
Subject: [PATCH 081/219] Update deposit_api.md

---
 deposit_api.md | 1 +
 1 file changed, 1 insertion(+)

diff --git a/deposit_api.md b/deposit_api.md
index 77fcef5..cba9b33 100644
--- a/deposit_api.md
+++ b/deposit_api.md
@@ -5,6 +5,7 @@
 | Date | Version | Changes |
 |------|---------|---------|
 | 2014-03-10 | v1 | Initial version |
+| 2015-01-15 | v2 | Mention PDF deposits |
 
 ## Background
 

From c6c0fb743c962de685fbaeeecae32e2ae65a64af Mon Sep 17 00:00:00 2001
From: Geoffrey Bilder 
Date: Wed, 6 May 2015 08:41:40 +0200
Subject: [PATCH 082/219] Update rest_api.md

---
 rest_api.md | 7 +++++--
 1 file changed, 5 insertions(+), 2 deletions(-)

diff --git a/rest_api.md b/rest_api.md
index 6c56c71..5e66108 100644
--- a/rest_api.md
+++ b/rest_api.md
@@ -27,14 +27,17 @@
 - 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.
+- v25, 2015-05-06, Added link to issue tracker. Removed Warning section.
 
 ## Background
 
 See the document, [CrossRef metadata best practice to support key performance indicators (KPIs) for funding agencies](http://api.crossref.org/docs/funder_kpi_metadata_best_practice.html), for background.
 
-## Warning
+## Reporting issues
 
-The API described here is in alpha. If you encounter problems with the API or the documentation, please report them to:
+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)
 

From 742f9c39672ae86b3c4cdaec190ee475fd2382a9 Mon Sep 17 00:00:00 2001
From: Vic Vijayakumar 
Date: Thu, 7 May 2015 13:17:15 -0400
Subject: [PATCH 083/219] Added a .gitignore and deleted the pesky .DS_Store
 file.

---
 .DS_Store  | Bin 6148 -> 0 bytes
 .gitignore |   1 +
 2 files changed, 1 insertion(+)
 delete mode 100644 .DS_Store
 create mode 100644 .gitignore

diff --git a/.DS_Store b/.DS_Store
deleted file mode 100644
index 36d5c4853795d5a2bf7f8c8998820f442b644998..0000000000000000000000000000000000000000
GIT binary patch
literal 0
HcmV?d00001

literal 6148
zcmeH~&u$Yj5XL{39HLfKDdNBhtpo=yAfV#FZ50&+S2%HD+5CYpTj*5v{ab0FiI&ulG}Gwyv>Fbk)qweSSiGb>xb#9x
zx{ZxFyZ;oOuk8OqU$g?}`cAv#JeaiF`MF`|FrFU2yjqBE;Ioi@P?kg;u?eJ@vtNZP>SXjmgTfSDGx4Qnlzv;v60=^&W
zIT^OxJ=HTE>oGmA;Qt-#JyyTTyyJUp#JP`+A)f3Tu$|GeGRsy&hd{4QxU)^V2LV%^
z7)T5x2L3Q$=R-y@%plnCiqpVxY;ujqtN)_y3FC@BgM!`jr?+4E$FN
zxX#JjlRhEEyLBr#yK6Jb2a1W!TL<(iRPj3Y4ZDi(P`ogfSp&=?t^?A8q(1_lhEyd6
Hu9bmb@w@P2

diff --git a/.gitignore b/.gitignore
new file mode 100644
index 0000000..e43b0f9
--- /dev/null
+++ b/.gitignore
@@ -0,0 +1 @@
+.DS_Store

From 9a2be71f6903e22cb8540dab5b5f4e04379bc4b3 Mon Sep 17 00:00:00 2001
From: Chris Callahan 
Date: Thu, 11 Jun 2015 10:27:41 -0400
Subject: [PATCH 084/219] remove curl examples that throw errors #60

---
 rest_api.md | 12 ------------
 1 file changed, 12 deletions(-)

diff --git a/rest_api.md b/rest_api.md
index 5e66108..5d47eca 100644
--- a/rest_api.md
+++ b/rest_api.md
@@ -188,14 +188,6 @@ Multiple filters can be specified by separating name:value pairs with a comma:
 
     http://api.crossref.org/funders/100000015/works?query=global+state&filter=has-orcid:true&rows=1
 
-### Example query using JSON in body of GET request
-
-Note that if you include a body in your `GET` request, any URI parameters will be ignored. In short, you cannot mix URI parameters and JSON queries.
-
-To use the API using JSON, pass the JSON in the body of the HTTP GET request like this:
-
-    curl -X GET -H "Content-Type: application/json" -d '{"query": "psychoceramics", "offset": 40, "rows": 20, "filter": {"has-orcid": true, "publisher": "10.5555"}}'  http://api.crossref.org/works
-
 ## Queries
 
 Queries support a subset of [DisMax](https://wiki.apache.org/solr/DisMax), so, for example you can refine queries as follows.
@@ -204,10 +196,6 @@ Queries support a subset of [DisMax](https://wiki.apache.org/solr/DisMax), so, f
 
     http://api.crossref.org/works?query=renear+-ontologies
     
-or using JSON
-
-    curl -X GET -H "Content-Type: application/json" -d '{"query": "renear -ontologies"}'  http://api.crossref.org/works
-
 ## Sorting
 
 Results from a listy response can be sorted by applying the `sort` and `order` parameters. Order

From 82e17673ccf247966f15037a445055a271102c50 Mon Sep 17 00:00:00 2001
From: Richard Littauer 
Date: Fri, 3 Jul 2015 11:58:50 -0400
Subject: [PATCH 085/219] Added a README with descriptions of each file,
 deleted dead file

---
 README.md         | 24 ++++++++++++++++++++++++
 funder_kpi_api.md |  5 -----
 2 files changed, 24 insertions(+), 5 deletions(-)
 create mode 100644 README.md
 delete mode 100644 funder_kpi_api.md

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..9eeb07f
--- /dev/null
+++ b/README.md
@@ -0,0 +1,24 @@
+# rest-api-doc
+
+Documentation for CrossRef's REST API.
+
+## How to us this repository
+
+This is a simple documentation repo. The following files can help you navigate CrossRef's API:
+
+ * [rest_api.md](rest_api.md) CrossRef REST API. This is the main file. 
+ * [rest_api_koans.md](rest_api_koans.md) - CrossRef API Koans. These are basic questions with their answers about how to use the API.
+ * [rest_api_tour.md](rest_api_tour.md) - These short examples show how the CrossRef REST APIs can be used to provide CrossPublisher suport for TDM applications. This demonstration is a bit of a paradox- it is targeted at a  non-technical audience who wants to understand a little but about the technical infrastructure that researchers can leverage for TDM applications.
+ * [ad_hoc_deposits.md](ad_hoc_deposits.md) - A Guide to Making Ad hoc XML Deposits Using CrossRef's Manual XML Deposit Interface
+ * [archive_query_api.md](archive_query_api.md) - Archive Arrangement Query API
+ * [deposit_api.md](deposit_api.md) - CrossRef RESTful Deposit API
+ * [resource_intended_use_hints.md](resource_intended_use_hints.md) - Resource Intended Use Hints Through CrossRef Metadata
+ * [scratch.md](scratch.md) - Content "Syndication" through CrossRef Metadata
+
+Example XML queries can be found in the example/ folder.
+
+### Key Perfomance Indicators
+
+This documentation has moved. Please [click here](http://api.crossref.org) to get to the new location. The canonical URL for this documentation is http://api.crossref.org . Please update your bookmarks.
+
+CrossRef metadata best practice to support key performance indicators (KPIs) for funding agencies is still available at [funder_kpi_metadata_best_practice.md](funder_kpi_metadata_best_practice.md).
\ No newline at end of file
diff --git a/funder_kpi_api.md b/funder_kpi_api.md
deleted file mode 100644
index 4f12822..0000000
--- a/funder_kpi_api.md
+++ /dev/null
@@ -1,5 +0,0 @@
-# CrossRef REST API
-
-This documentation has moved. Please [click here](http://api.crossref.org) to get to the new location.
-
-The canonical URL for this documentation is http://api.crossref.org . Please update your bookmarks.

From 7d2a9b8f1abbd2516f487514ec0cabcf1eb124da Mon Sep 17 00:00:00 2001
From: Alf Eaton 
Date: Wed, 7 Oct 2015 17:22:46 +0100
Subject: [PATCH 086/219] Fix *_distribution_opts documentation

* Fix documentation links
* `reference_distribution_opt` should be `reference_distribution_opts`
---
 funder_kpi_metadata_best_practice.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/funder_kpi_metadata_best_practice.md b/funder_kpi_metadata_best_practice.md
index b8a5a01..173b0db 100644
--- a/funder_kpi_metadata_best_practice.md
+++ b/funder_kpi_metadata_best_practice.md
@@ -247,11 +247,11 @@ The more metadata that publishers record for publications arising from agency fu
 
 #### Distributing standard bibliographic metadata
 
-Metadata deposited to CrossRef is made available freely via numerous CrossRef query APIs. However all deposited metadata is subject to opt-outs in the case of bulk distribution APIs and data dumps. In order to make sure that bibliographic metadata for publications arising from agency funding is maximally available, publishers __should__ consider setting the value of the `` element for DOIs to `any`.  Further details can be found in [CrossRef's schema documentation for the `` element.](http://www.crossref.org/schema/documentation/4.3.4/NO_NAMESPACE.html#metadata_distribution_opts.att_metadata_distribution_opts)
+Metadata deposited to CrossRef is made available freely via numerous CrossRef query APIs. However all deposited metadata is subject to opt-outs in the case of bulk distribution APIs and data dumps. In order to make sure that bibliographic metadata for publications arising from agency funding is maximally available, publishers __should__ consider setting the value of the `` element for DOIs to `any`.  Further details can be found in [CrossRef's schema documentation for the `` element.](http://www.crossref.org/help/schema_doc/4.3.6/4_3_6.html#metadata_distribution_opts.att)
 
 #### Distributing references
 
-References made in publications arising from agency funding can provide agencies with an overview of what literature is considered important in the fields that they fund. Many publishers deposit references to CrossRef as part of their participation CrossRef's [CitedBy](http://www.crossref.org/citedby/index.html) service. However, participation in CitedBy does not automatically make references available via CrossRef's standard APIs. In order for publishers to distribute references along with standard bibliographic metadata, publishers need to set the `` element to `any` for each DOI deposit where they want to make references openly available. By setting this element, references for the DOI will be distributed without restriction through all of CrossRefs APIs and bulk metadata dumps. Further details can be found in [CrossRef's schema documentation for the `` element.](http://www.crossref.org/schema/documentation/4.3.4/4.3.4.html#reference_distribution_opts.att)
+References made in publications arising from agency funding can provide agencies with an overview of what literature is considered important in the fields that they fund. Many publishers deposit references to CrossRef as part of their participation CrossRef's [CitedBy](http://www.crossref.org/citedby/index.html) service. However, participation in CitedBy does not automatically make references available via CrossRef's standard APIs. In order for publishers to distribute references along with standard bibliographic metadata, publishers need to set the `` element to `any` for each DOI deposit where they want to make references openly available. By setting this element, references for the DOI will be distributed without restriction through all of CrossRefs APIs and bulk metadata dumps. Further details can be found in [CrossRef's schema documentation for the `` element.](http://www.crossref.org/help/schema_doc/4.3.6/4_3_6.html#reference_distribution_opts.att)
 
 #### CrossMark
 

From ef3f5a93d2e5c8ce76042baa92e3efd07f08a64e Mon Sep 17 00:00:00 2001
From: Karl Jonathan Ward 
Date: Tue, 20 Oct 2015 11:52:18 +0100
Subject: [PATCH 087/219] Filters for created, affiliations, assertions

---
 rest_api.md | 14 +++++++++-----
 1 file changed, 9 insertions(+), 5 deletions(-)

diff --git a/rest_api.md b/rest_api.md
index 5d47eca..592c0b7 100644
--- a/rest_api.md
+++ b/rest_api.md
@@ -28,7 +28,7 @@
 - v23, 2014-09-01, semantics of mutliple filters, dot filters
 - 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`
 ## Background
 
 See the document, [CrossRef metadata best practice to support key performance indicators (KPIs) for funding agencies](http://api.crossref.org/docs/funder_kpi_metadata_best_practice.html), for background.
@@ -235,8 +235,8 @@ Filters allow you to narrow queries. All filter results are lists.  The followin
 | `until-deposit-date` | `{date}` | metadata last (re)deposited before (inclusive) `{date}` |
 | `from-update-date` | `{date}` | Metadata updated since (inclusive) `{date}`. Currently the same as `from-deposit-date`. |
 | `until-update-date` | `{date}` | Metadata updated before (inclusive) `{date}`. Currently the same as `until-deposit-date`. |
-| `from-first-deposit-date` | `{date}` | metadata first deposited since (inclusive) `{date}` [^*] |
-| `until-first-deposit-date` | `{date}` | metadata first deposited before (inclusive) `{date}` [^*] |
+| `from-created-date` | `{date}` | metadata first deposited since (inclusive) `{date}` |
+| `until-created-date` | `{date}` | metadata first deposited before (inclusive) `{date}` |
 | `from-pub-date` | `{date}` | metadata where published date is since (inclusive) `{date}` |
 | `until-pub-date` | `{date}` | metadata where published date is before (inclusive)  `{date}` |
 | `has-license` | | metadata that includes any `` elements. |
@@ -265,8 +265,12 @@ Filters allow you to narrow queries. All filter results are lists.  The followin
 | `type-name` | | metadata for records with an exacty matching type label |
 | `award.number` | `{award_number}` | metadata for records with a matching award nunber. Optionally combine with `award.funder` |
 | `award.funder` | `{funder doi or id}` | metadata for records with an award with matching funder. Optionally combine with `award.number` |
-
-[^*]: Not implemented yet.
+| `assertion-group` | | metadata for records with an assertion in a particular group |
+| `assertion` | | metadata for records with a particular named assertion |
+| `affiliation` | | metadata for records with at least one contributor with the given affiliation |
+| `has-affiliation` | | metadata for records that have any affiliation information |
+| `alternative-id` | | metadata for records with the given alternative ID, which may be a publisher-specific ID, or any other identifier a publisher may have provided |
+| `article-number` | | metadata for records with a given article number |
 
 ### Multiple filters
 

From a85d15fdaf2e4faf463bb5279ba7579635c65ed5 Mon Sep 17 00:00:00 2001
From: Karl Jonathan Ward 
Date: Tue, 20 Oct 2015 11:52:41 +0100
Subject: [PATCH 088/219] Fix formatting of background header

---
 rest_api.md | 1 +
 1 file changed, 1 insertion(+)

diff --git a/rest_api.md b/rest_api.md
index 592c0b7..1c50985 100644
--- a/rest_api.md
+++ b/rest_api.md
@@ -29,6 +29,7 @@
 - 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`
+
 ## Background
 
 See the document, [CrossRef metadata best practice to support key performance indicators (KPIs) for funding agencies](http://api.crossref.org/docs/funder_kpi_metadata_best_practice.html), for background.

From 23a5e00842613e634ba2e3caadc0be6cbd9b38c5 Mon Sep 17 00:00:00 2001
From: Daniel Mietchen 
Date: Tue, 27 Oct 2015 01:00:54 +0100
Subject: [PATCH 089/219] fixed copy-paste error

---
 rest_api_tour.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/rest_api_tour.md b/rest_api_tour.md
index cbdfd38..c8f6f43 100644
--- a/rest_api_tour.md
+++ b/rest_api_tour.md
@@ -110,7 +110,7 @@ Now what DOIs do  Elsevier have that match our criteria?
 
 Now what is Hindawi's CrossRef member id number?
 
-    http://api.crossref.org/members?query=elsevier
+    http://api.crossref.org/members?query=hindawi
 
 Now lets get some Hindawi articles that match the criteria:
 

From a2b8bce41415f87c310d35303154989492110d4f Mon Sep 17 00:00:00 2001
From: Geoffrey Bilder 
Date: Wed, 28 Oct 2015 16:15:29 +0000
Subject: [PATCH 090/219] cleanup, add info about registering DOIs for accpeted
 manuscripts even when they are not available online

---
 funder_kpi_metadata_best_practice.md | 164 ++++++++++++++++++++-------
 1 file changed, 122 insertions(+), 42 deletions(-)

diff --git a/funder_kpi_metadata_best_practice.md b/funder_kpi_metadata_best_practice.md
index b8a5a01..78c4548 100644
--- a/funder_kpi_metadata_best_practice.md
+++ b/funder_kpi_metadata_best_practice.md
@@ -1,4 +1,7 @@
-# CrossRef metadata best practice to support key performance indicators (KPIs) for funding agencies
+# Using Crossref metadata to enable auditing of conformance to funder mandates: A Guide for publishers
+
+## Table of Contents
+
 
 
 ## Version History
@@ -14,24 +17,35 @@
 - V09: 2013-12-02, Added XML deposit examples
 - v10: 2013-12-03, Updated `` element documentation to reflect latest NISO work. Added information about licensing CrossRef metadata to FAQ (hint, no license required for free APIs). Added labs email address. Changed formatting.
 - v11: 2013-12-11, Added third party archive arrangements section. Updated examples to include archive locations.
+- v12: 2015-11-27, Revisions to describe deposit workflow to support alerting funders/instituions when content has been "accepted". Pointers to latest schemas. General cleanup.
 
-## Warning
-As of 2013–12–03 the `` element has not yet been incorporated into the CrossRef deposit schema.
+## Contact info
 
 If you encounter problems with the API or the documentation, please report them to:
 
 ![](http://labs.crossref.org/wp-content/uploads/2013/01/labs_email.png)
 
 ## Background
-Funding agencies and publishers are interested in being able to measure Key Performance Indicators (KPIs) related to mandates such the February 22nd OSTP memo on *[Public Access to the Results of Federally Funded Research](http://www.whitehouse.gov/blog/2013/02/22/expanding-public-access-results-federally-funded-research)*.
-CrossRef is extending its FundRef Application Programming Interfaces (APIs) to enable funding agencies and publishers to query CrossRef metadata in support of generating such KPIs. Organisations such as *[CHORUS](http://publishers.org/press/107/)* and *[SHARE](http://www.arl.org/news/arl-news/2773-shared-access-research-ecosystem-proposed-by-aau-aplu-arl)* can make use of these APIs in order to create KPI Dashboards measuring, amongst other things:
 
-1. Publications relating to research funded by particular agencies.
-2. The licenses under which said publications have been released.
-3. The location of the full text of the Best Available Version (BAV) for said publications for both reading and Text & Data Mining (TDM) applications.
-4. The long-term preservation arrangements that have been made for the VOR of said publications.
+Funders are increasingly setting mandates around publications that result from research they have funded. The mandates include specifications about licenses, embargoes, and notifications of publication acceptance and/or publication. This poses logistical problems for all the parties involved. Funders will need a way to track outputs from thousands of publishers. Publishers will need a standard and efficient way to demonstrate conformance to the mandates. All the stakeholders in the process (funders, publishers, institutions and researchers) will span disciplines, institutions, geographies and jurisdictions. Crossref was setup specifically to deal with these sorts of multiple bilateral relationships.
+
+Crossref has extended its metadata schemas and Application Programming Interfaces (APIs) to enable funding agencies, institutions and publishers to use CrossRef as a metadata source that can be used to track research that is subject to these mandates and to ensure that said research is being disseminated according to the requirements of the mandates.
+
+Funders, institutions, publishers and third parties providing research information management tools (e.g. *[CHORUS](http://publishers.org/press/107/)*, *[SHARE](http://www.arl.org/news/arl-news/2773-shared-access-research-ecosystem-proposed-by-aau-aplu-arl)*,*[Symplectic](http://symplectic.co.uk)* can make use of Crossref APIs and metadata in order to identify:
 
-The CrossRef extended APIs, of course, will only work if publishers supply the appropriate metadata. This document outlines the metadata that publishers will need to provide in order to support such KPI reporting.
+- Publications relating to research supported by particular funders.
+- Publications from particular researchers identified by their ORCID ID.
+- The bibliographic metadata for said publications.
+- The licenses under which said publications have been released.
+- Any embargoes applied to said publications.
+- The location of the full text of the Best Available Version (BAV) for said publications for both reading and text & data mining (TDM) applications.
+- The long-term preservation arrangements that have been made for the VOR of said publications.
+- The ORCIDs associated with those publications.
+- Any updates (errata, corrigenda, retractions) applied to said publications.
+
+This data can be propagated by publisher at any time after publication acceptance- according to the requirements of the relevant mandates.
+
+The CrossRef extended APIs, of course, will only work if publishers supply the appropriate metadata and follow the specified metadata deposit workflows. This document outlines the metadata that publishers will need to provide and the metadata deposit workflows they will need to support in order to advertise their conformance to funder mandates.
 
 ## Conventions
 
@@ -41,31 +55,35 @@ Although this document is not an RFC, it will follow the conventions of __[rfc21
 2. __must not__ - This phrase, or the phrase "SHALL NOT", mean that the definition is an absolute prohibition for meeting best practice.
 3. __should__ - This word, or the adjective "RECOMMENDED", mean that there may exist valid reasons in particular circumstances to ignore a particular item, but the full implications must be understood and carefully weighed before choosing a different course.
 4. __should not__ - This phrase, or the phrase "NOT RECOMMENDED",  mean that there may exist valid reasons in particular circumstances when the particular behavior is acceptable or even useful, but the full implications should be understood and the case carefully weighed before implementing any behavior described with this label.
+5. __may__   This word, or the adjective "OPTIONAL", mean that an item is truly optional.  One vendor may choose to include the item because a particular marketplace requires it or because the vendor feels that it enhances the product while another vendor may omit the same item. An implementation which does not include a particular option MUST be prepared to interoperate with another implementation which does include the option, though perhaps with reduced functionality. In the same vein an implementation which does include a particular option MUST be prepared to interoperate with another implementation which does not include the option (except, of course, for the feature the option provides.)
 
 ## Summary
 
-In order to support basic agency and publisher KPIs:
+In order to advertise conformance to funder mandates, Crossref members:
 
-- Publishers __must__ record funder information in their CrossRef deposits  
-- Publishers __must__ deposit the FundRef funder identifiers corresponding to their funder names where these exist in the FundRef Registry
-- Publishers __should__ record award numbers when possible.
-- The Publisher __should__ record funding information within CrossMark records __if__ they are either implementing CrossMark or are planning to implement CrossMark within the next two years. 
-- Publishers __should__ record licensing information if they have it by means of a URI specifying the license under which the publication is made.
+- __must__ record funder information in their CrossRef deposits  
+- __must__ deposit the FundRef funder identifiers corresponding to their funder names where these exist in the FundRef Registry
+-  __should__ record award numbers when possible.
+- __should__ record funding information within CrossMark records __if__ they are either implementing CrossMark or are planning to implement CrossMark within the next two years.
+- __should__ record licensing information if they have it by means of a URI specifying the license under which the publication is made.
 - If publishers do not have licensing information, they __should__ record a placeholder URI and fill in the target of the URI once they have agreed on licensing information.
-- Publishers __should__ record full text links to the readable version(s) of the document. This may include different resources for the Version of Record (VOR) and Author Accepted Manuscript (AM).
-- Publishers __should__ record full text links to representations of the document that are made available for TDM. These may be the same or different to the "readable" versions of the document pointed to above.
+- __should__ record full text links to the readable version(s) of the document. This may include different resources for the Version of Record (VOR) and Author Accepted Manuscript (AM).
+- __should__ record full text links to representations of the document that are made available for TDM. These may be the same or different to the "readable" versions of the document pointed to above.
 - Where they are recording multiple versions of the document (e.g. AM & VOR), the publisher __should__ map licensing information to the specific resource versions.
-- Publishers __should__ record full text links to archived versions of the document identified by the CrossRef DOI.
-- Publishers __should__ record archive arrangements made with third party archiving organizations where the document identified by the CrossRef DOI is archived with the third party.
+- __should__ record full text links to archived versions of the document identified by the CrossRef DOI.
+- __should__ record archive arrangements made with third party archiving organizations where the document identified by the CrossRef DOI is archived with the third party.
+
+In order to enhance the utility of CrossRef metadata to funders and in order to enable more sophisticated funder/publisher KPIs, Crossref members:
+
+- __should__ consider participating in CrossMark in order to record updates, errata, corrigenda,retractions and withdrawals.
+- __should__ consider depositing abstracts using CrossRef's JATS abstract element support.
+- __should__ consider collecting and depositing ORCIDs for publication authors.
+- __should__ consider making the bibliographic metadata and references for documents resulting from agency funding maximally available by overriding CrossRef opt-outs using the `` and `` elements.
 
-In order to enhance the utility of CrossRef metadata to agencies and in order to enable more sophisticated agency/publisher KPIs:
+In order to alert funders of relevant publications as soon as possible, Crossref members:
 
-- Publishers __should__ consider participating in CrossMark in order to record updates, errata, corrigenda,retractions and withdrawals. 
-- Publishers __should__ consider depositing abstracts using CrossRef's JATS abstract element support.
-- Publishers __should__ consider collecting and depositing ORCIDs for publication authors.
-- Publishers __should__ consider making the bibliographic metadata and references for documents resulting from agency funding maximally available by overriding CrossRef opt-outs using the `` and `` elements. 
+- __should__ consider assigning and registering DOIs at acceptance
 
- 
 ## Funding information
 
 CrossRef supports the recording of funding information for a publication via its [FundRef](http://www.crossref.org/fundref/) program. FundRef defines an open, standard [registry of funder names and funder identifiers](http://www.crossref.org/fundref/fundref_registry.html) that can be used in order to increase the accuracy of the funding information recorded. Although FundRef supports recording award_numbers along with funder identifiers, FundRef does __not__ define standards for recording award numbers as practice varies greatly across funders.
@@ -73,16 +91,16 @@ CrossRef supports the recording of funding information for a publication via its
 To support funder KPIs, members __must__ deposits funder metadata using the specifications defined for the FundRef program. Specifically, when depositing metadata you:
 
 
-1. __must__ include funder information. 
+1. __must__ include funder information.
 2. __must not__ deposit your funder names without at least trying to map them to FundRef identifiers in the FundRef registry. Depositing funder names that are included in the FundRef registry, but without their respective FundRef Funder Identifiers, will pollute the FundRef metadata and lower the value of the service for all participants. Note that the KPI APIs will only work for Funder metadata that includes FundRef Funder Identifiers.
 3. __should__ include award numbers in FundRef metadata when possible. Although the standard KPI API does not make direct use of award numbers, individual agencies may be able to make use of included award numbers where found.
-4. __should__ deposit FundRef data as part of a CrossMark record if you (the publisher) already are (or *are planning* to become) a participant in CrossMark. There are two reasons for this: First, it ensures that the Funder Metadata is available __both__ in a standard machine readable format __AND__ via a standard UI for readers. Second, it ensures that the Funder metadata is made maximally reusable via a CC Zero license waiver. Note that publishers do not __need__ to have implemented CrossMark yet to deposit Funder metadata via CrossMark. We expect that publishers may take a year or more before they have fully implemented all of CrossMark's features. 
+4. __should__ deposit FundRef data as part of a CrossMark record if you (the publisher) already are (or *are planning* to become) a participant in CrossMark. There are two reasons for this: First, it ensures that the Funder Metadata is available __both__ in a standard machine readable format __AND__ via a standard UI for readers. Second, it ensures that the Funder metadata is made maximally reusable via a CC Zero license waiver. Note that publishers do not __need__ to have implemented CrossMark yet to deposit Funder metadata via CrossMark. We expect that publishers may take a year or more before they have fully implemented all of CrossMark's features.
 
-See CrossRef's Help pages for [Technical details on depositing FundRef metadata.](http://help.crossref.org/#fundref) 
+See CrossRef's Help pages for [Technical details on depositing FundRef metadata.](http://help.crossref.org/#fundref)
 
 ## License information
 
-One of the main drivers for the FunRef KPI API is that many funders are required to report on the public availability of the results and publications arising from funder-financed research. Funders are therefor interested in understanding how publications related to funded research are licensed. 
+One of the main drivers for the FunRef KPI API is that many funders are required to report on the public availability of the results and publications arising from funder-financed research. Funders are therefor interested in understanding how publications related to funded research are licensed.
 
 To deposit license information, publishers __must__ use the `` element. The value of the `` element __must__ be a stable HTTP URI which points to a human-readable document that either includes (or guides the reader to) any copyright and/or licensing information related to the CrossRef DOI of the content. The URI __must__ point either to a location on the publisher's site or to the stable location of any well-known licenses such as those of the Creative Commons.  
 
@@ -103,7 +121,7 @@ You can deposit multiple `` elements- so the following would indica
     http://www.psychoceramics.org/non_commercial_license_v1.html
     http://www.psychoceramics.org/commercial_license_v1.html
 
-### Embargos
+### Embargoes
 
 Publishers may want to record that a document is under embargo. In other words, that it is available under access control and a proprietary license for a set period of time, after which it is available under an open license. Publishers wishing to record embargoes __should__ use the optional `start_date` attribute on the `` element.
 
@@ -123,8 +141,8 @@ The `start_date` attribute can be combined with multiple `` element
 
 Note that there is __no__ corresponding `end_date` attribute for the `` element. This is because including end dates could introduce ambiguities. For example:
 
-- Open Licenses, such as CC, do not have "end dates". 
-- With end dates, it would be possible to inadvertently record "gaps" between licenses. 
+- Open Licenses, such as CC, do not have "end dates".
+- With end dates, it would be possible to inadvertently record "gaps" between licenses.
 
 You might ask why one should record a license that starts in the future? Wouldn't it be better to just update the `` element at the time the license changes? By recording that another license takes effect in the future, you are informing the consumer of the metadata that the current restricted license is only for the embargo period. In short, you are recording the __intent__ to change the license when the embargo is done. Furthermore, providing additional metadata for a current publication at some future date is an additional chore for the publisher that might well be overlooked.
 
@@ -132,7 +150,7 @@ In the above examples, the `` element is unqualified and should the
 
 ## Recording links to full text and/or archived versions of documents, etc.
 
-Funders are not just interested in reporting on the licensing terms of publications resulting from funder-financed research. They are also interested in making sure that the full text content of the BAV is made available for reading, automated processing and archiving. 
+Funders are not just interested in reporting on the licensing terms of publications resulting from funder-financed research. They are also interested in making sure that the full text content of the BAV is made available for reading, automated processing and archiving.
 
 To this end, publishers need to be able to record links to the full text of the content to which a DOI refers. Additionally, publishers will want to offer different versions (e.g. AM or VOR) and different representations (e.g. PDF for viewing, XML for TDM, etc.) of the content tailored for specific applications.
 
@@ -144,7 +162,7 @@ The `` element in CrossRef metadata is most often used to record an HT
 
 CrossRef has extended the ability to record multiple `` elements in order to allow the recording of URIs which point to the full text of content identified by the CrossRef DOI. The publisher can record multiple representations of the full text (e.g. PDF, XML, plain text) using the new `mime_type` attribute and then, through their access control systems, control who is able to reach which representation and under which conditions.
 
-Note that, by recording a `` that points to the full text, you are not necessarily guaranteeing that the URI will be accessible 
+Note that, by recording a `` that points to the full text, you are not necessarily guaranteeing that the URI will be accessible
 
 Note also that the publisher could theoretically choose only to deposit `` elements for full text representations once an embargo has ended. However, this approach may prove fraught, as any mistakes or delays in the redeposit process might lead the funding agency to believe that the publisher has not made the relevant content accessible at the end of the embargo period.
 
@@ -196,18 +214,18 @@ Detailed information on recording licensing information in CrossRef metadata can
 
 ## "Libre" vs "Gratis"
 
-The license information recorded in the `` element can tell you what you are allowed to do with the resources the licenses point to, but they do not say anything about whether or not there is a monetary charge involved. 
+The license information recorded in the `` element can tell you what you are allowed to do with the resources the licenses point to, but they do not say anything about whether or not there is a monetary charge involved.
 In order to allow a publisher to record whether access to the content requires payment, CrossRef supports a new `` element. The `` element is an empty element. It can include two attributes, a `start_date` and an `end_date`. The `` elements works as follows:
 
  - The presence of a  element in CrossRef metadata __should_ be interpreted to mean that the full text content pointed to by the  DOI resource is available "gratis" during the time period specified by the start_date and end_date attributes.
- - If the  element only includes a `start_date` attribute, then the element __should__ be interpreted to mean that the content pointed to by the DOI resource will be made gratis from `start_date` on. 
+ - If the  element only includes a `start_date` attribute, then the element __should__ be interpreted to mean that the content pointed to by the DOI resource will be made gratis from `start_date` on.
  - If the  element only includes a `end_date` attribute, then the element __should__ be interpreted to mean that the content pointed to by the DOI resource will be made gratis from the publication date to and including the `end_date`.
  - If the  element has __no__ `start_date` __or__ `end_date` attributes, then the element __should__ be interpreted to mean that the content pointed to by the DOI resource is available "gratis" from the date of publication on.
  - If the  element is not present in the DOI record, one __should not__ assume that the resource pointed at by the DOI is available to read "gratis".
 
 
  When the `` element is combined with the `` element, the publisher can record sophisticated information about the availability and reusability of content. For example:
- 
+
 **restrictive licenses and possibly a payment**
 
     http://tinypublisher.org/licenses/proprietary.html
@@ -239,7 +257,69 @@ Publishers can record the archive arrangement or archive intention of a document
 	  
     
 
-CrossRef maintains a vocabulary of archive locations within the CrossRef deposit schema. The latest list of possible archive location values can be found in the documentation for the [ `` element ](http://www.crossref.org/schema/documentation/4.3.4/4.3.4.html#archive).
+CrossRef maintains a vocabulary of archive locations within the CrossRef deposit schema. The latest list of possible archive location values can be found in the documentation for the [ `` element ](http://www.crossref.org/help/schema_doc/4.3.6/4.3.6.html).
+
+## Assigning and registering DOIs at acceptance
+
+Funders and institutions would like to be notified of impending publications as early as possible. Some mandates, like that issued by HEFCE, even require that institutional repositories be notified of an impending relevant publication as soon as the manuscript is accepted- Even if said manuscript has not yet been made available.
+
+### Assigning and registering DOIs for manuscripts that the publisher has made avaialble online
+
+Crossref has always supported the deposit of DOIs for accepted manuscripts __if__ said manuscripts have also been made available online. This is a common practice that goes under various names including “publish ahead of print,” “article in progress,” “article in press,” “online ahead of print,” “online first”, etc. Crossref rules state that in this situation, Crossref members:
+
+ - __may__ assign DOIs to accepted manuscripts
+ - __should__ carry over the DOI assigned to the accepted manuscript to the final published version.
+ - __should__ update the metadata for the DOI with that of the final published version.
+
+ These rules reflect that, though there may be significant value added by he publisher between acceptance and final publication,  the accepted and the final published version are interchangeable from a citation point of view. This is because the transition from acceptance to the final published version should not introduce any changes that are likely to effect the interpretation of crediting of the work.  
+
+### Assigning and registering DOIs for manuscripts that the publisher has not yet made available online
+
+*(Please note that this section includes a draft recommendation which have not yet been ratified by our members or implemented. We are soliciting feedback on this section of the  document.)*
+
+Crossref will support a new mechanism and workflow to support the registration of DOIs for accepted manuscripts __before__ they are made publicly available online. This feature can be used by publishers as a mechanism for informing funders and institutions of impending publications. To use this, publishers will deposit a special type of Crossref record called "registered content."
+
+The schema and rules governing the "registered content" type attempt to balance the publisher's desire to control publicity around their content with the requirements that funders and institutions have to know as soon as possible when content governed under their mandates has been accepted for publication. Once the publication is made available online (either as an accepted manuscript or version of record), then the publisher can simply redeposit and replace the "registered content" record with a full metadata record using a Crossref schema appropriate to the publication (e.g. journal article).
+
+DOIs for "registered content" will not resolve to a publisher's landing page. Rather, they will resolve to a landing page controlled by Crossref. This landing page will __minimally__ display the DOI, the acceptance date, and an "intent to publish statement" which, by default will read as follows (with the appropriate {variables} filled in):
+
+>> The DOI {DOI} has been registered for content that was accepted for publication by {publisher name} on {date_of_acceptance}. When this content is available, the publisher will update this DOI, at which point it will automatically redirect you to the copy on the publisher's site.
+
+Publishers will able to apply limited customizations to the landing page. These include:
+
+- a custom "intent to publish" statement which will replace the default one provided by Crossref.
+- a publisher logo to display at the top of the landing page.
+- the display of all provided optional extra metadata such as funder identifiers, ORCID ids, license information, etc.
+- a CrossMark, to handle situations in which a publisher rescinds an acceptance.
+
+If the publisher provides metadata beyond that required, it will be displayed on the landing page below the "intent to publish" statement. "Registered content" records will also be made available through the CrossRef REST API and through Crossref metadata search.
+
+By having Crossref control the landing page for "registered content" we can ensure that:
+
+- there is always a landing page- even for content that it not yet available online
+- metadata is displayed consistently for registered content
+- members do not abuse the lightweight metadata requirements of "registered content" in order to register other content types more easily.
+
+The schema for "registered content" will only support a minimal subset of metadata that can be used by funders and institutions to detect and flag impending publications that are relevant to them.
+
+Registered content DOI records:
+
+- __must__ include a DOI
+- __must__ include a date of acceptance
+- __must__ include the publisher name
+- __must__ must be replaced with appropriate full metadata using an appropriate schmea for the content type when the publisher makes the content publically available
+- __should__ include an "intent to publish statement." If the publisher does not provide an "intent to publish statement" of their own, then Crossref will provide a default statement.
+- __may__ include a logo to diplay at the top of the landing page
+- __may__ include a custom "intent to publish statement."
+- __should__ include funder information
+- __should__ include FundRef funder identifiers corresponding to their funder names where these exist in the FundRef Registry
+- __should__ include ORCIDs
+- __should__ include license information
+- __should__ author affiliation information
+- __may__ include the publication title
+- __may__ include the item title (e.g. article title)
+
+The "registered content" type is specifically designed for publishers who want to be able to inform funders and institutions that an article has been accepted for publication, even when the publisher is for some reason unable to make the accepted manuscript publicly available. The landing page and metadata for the "registered content" type allow the publisher to provide as much data as is needed to notify interested parties, yet not reveal commercially or promotionally sensitive information about their upcoming publications. When the publisher is ready to make the content available, they simply have to replace the temporary "registered content" record with a permanent DOI record. 
 
 ## Bonus points
 
@@ -255,7 +335,7 @@ References made in publications arising from agency funding can provide agencies
 
 #### CrossMark
 
-[CrossMark](http://www.crossref.org/crossmark/) provides a standard mechanism for alerting researchers to updates to published documents- including corrections, errata, corrigenda retractions and withdrawals. Use of the CrossMark service sends a signal to researchers and agencies that publishers are committed to maintaining the integrity of the scholarly record. 
+[CrossMark](http://www.crossref.org/crossmark/) provides a standard mechanism for alerting researchers to updates to published documents- including corrections, errata, corrigenda retractions and withdrawals. Use of the CrossMark service sends a signal to researchers and agencies that publishers are committed to maintaining the integrity of the scholarly record.
 
 Additionally, CrossMark also provides a standard, cross-publisher, user interface that researchers can use to view FundRef information and licensing information. This user interface works both from publisher landing pages and from published PDFs. More information can be found on the [CrossMark support site](http://crossmarksupport.crossref.org/)
 
@@ -269,11 +349,12 @@ CrossRef supports the deposit of abstracts conforming to the [JATS](http://jats.
 
 [ORCID](http://www.orcid.org/)s are unique identifiers for researchers. CrossRef supports the deposit of ORCIDs for authors. The presence of ORCIDs in CrossRef metadata will, in turn, allow agencies to tie agency funded research publications directly to researchers. Widespread use of ORCIDs in CrossRef deposits could even let agencies start to develop publication KPIs for researchers that they fund. Further details on CrossRef's ORCID support can be found in the [CrossRef Schema Documentation of the `` element](http://www.crossref.org/schema/documentation/4.3.4/4.3.4.html#ORCID)
 
+
 ## Frequently Asked Questions
 
 **Q:** What license applies to the metadata retrieved by the [CrossRef APIs to support key performance indicators (KPIs) for funding agencies](funder_kpi_api.html)?
 
    
-**A:** 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/). 
+**A:** 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/).
 
 **Q:** What does it mean if a `` element has no `start_date` attribute?
 
    
@@ -320,4 +401,3 @@ one updating funding information, the other updating license information.
 - [Partial deposit of funding information without CrossMark](examples/partial-funders.xml)
 - [Partial deposit of license information without CrossMark](examples/partial-licenses.xml)
 - [Partial deposit of a CrossMark with license and funding information](examples/partial-crossmark.xml)
- 

From 64f8fd1ecb9451f44f8ccdd9fdc0c0a9faf1dc67 Mon Sep 17 00:00:00 2001
From: Geoffrey Bilder 
Date: Wed, 28 Oct 2015 16:21:25 +0000
Subject: [PATCH 091/219] make headings clearer

---
 funder_kpi_metadata_best_practice.md | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/funder_kpi_metadata_best_practice.md b/funder_kpi_metadata_best_practice.md
index 78c4548..05d8cf7 100644
--- a/funder_kpi_metadata_best_practice.md
+++ b/funder_kpi_metadata_best_practice.md
@@ -261,9 +261,9 @@ CrossRef maintains a vocabulary of archive locations within the CrossRef deposit
 
 ## Assigning and registering DOIs at acceptance
 
-Funders and institutions would like to be notified of impending publications as early as possible. Some mandates, like that issued by HEFCE, even require that institutional repositories be notified of an impending relevant publication as soon as the manuscript is accepted- Even if said manuscript has not yet been made available.
+Funders and institutions would like to be notified of impending publications as early as possible. Some mandates, like the [one issued by HEFCE](http://www.hefce.ac.uk/pubs/year/2015/CL,202015/), even require that institutional repositories be notified of an impending relevant publication as soon as the manuscript is accepted- even if said manuscript has not yet been made available online.
 
-### Assigning and registering DOIs for manuscripts that the publisher has made avaialble online
+### Assigning and registering DOIs for manuscripts that the publisher *has* made avaialble online
 
 Crossref has always supported the deposit of DOIs for accepted manuscripts __if__ said manuscripts have also been made available online. This is a common practice that goes under various names including “publish ahead of print,” “article in progress,” “article in press,” “online ahead of print,” “online first”, etc. Crossref rules state that in this situation, Crossref members:
 
@@ -273,7 +273,7 @@ Crossref has always supported the deposit of DOIs for accepted manuscripts __if_
 
  These rules reflect that, though there may be significant value added by he publisher between acceptance and final publication,  the accepted and the final published version are interchangeable from a citation point of view. This is because the transition from acceptance to the final published version should not introduce any changes that are likely to effect the interpretation of crediting of the work.  
 
-### Assigning and registering DOIs for manuscripts that the publisher has not yet made available online
+### Assigning and registering DOIs for manuscripts that the publisher *has not yet* made available online
 
 *(Please note that this section includes a draft recommendation which have not yet been ratified by our members or implemented. We are soliciting feedback on this section of the  document.)*
 
@@ -319,7 +319,7 @@ Registered content DOI records:
 - __may__ include the publication title
 - __may__ include the item title (e.g. article title)
 
-The "registered content" type is specifically designed for publishers who want to be able to inform funders and institutions that an article has been accepted for publication, even when the publisher is for some reason unable to make the accepted manuscript publicly available. The landing page and metadata for the "registered content" type allow the publisher to provide as much data as is needed to notify interested parties, yet not reveal commercially or promotionally sensitive information about their upcoming publications. When the publisher is ready to make the content available, they simply have to replace the temporary "registered content" record with a permanent DOI record. 
+The "registered content" type is specifically designed for publishers who want to be able to inform funders and institutions that an article has been accepted for publication, even when the publisher is for some reason unable to make the accepted manuscript publicly available. The landing page and metadata for the "registered content" type allow the publisher to provide as much data as is needed to notify interested parties, yet not reveal commercially or promotionally sensitive information about their upcoming publications. When the publisher is ready to make the content available, they simply have to replace the temporary "registered content" record with a permanent DOI record.
 
 ## Bonus points
 

From 9a6d08119767bc73cc55b1334fe0aa36b47b7a15 Mon Sep 17 00:00:00 2001
From: Geoffrey Bilder 
Date: Wed, 28 Oct 2015 16:23:51 +0000
Subject: [PATCH 092/219] add TOC

---
 funder_kpi_metadata_best_practice.md | 35 ++++++++++++++++++++++++++++
 1 file changed, 35 insertions(+)

diff --git a/funder_kpi_metadata_best_practice.md b/funder_kpi_metadata_best_practice.md
index 05d8cf7..1e72f93 100644
--- a/funder_kpi_metadata_best_practice.md
+++ b/funder_kpi_metadata_best_practice.md
@@ -2,6 +2,37 @@
 
 ## Table of Contents
 
+
+
+- [Using Crossref metadata to enable auditing of conformance to funder mandates: A Guide for publishers](#using-crossref-metadata-to-enable-auditing-of-conformance-to-funder-mandates-a-guide-for-publishers)
+	- [Table of Contents](#table-of-contents)
+	- [Version History](#version-history)
+	- [Contact info](#contact-info)
+	- [Background](#background)
+	- [Conventions](#conventions)
+	- [Summary](#summary)
+	- [Funding information](#funding-information)
+	- [License information](#license-information)
+		- [Embargoes](#embargoes)
+	- [Recording links to full text and/or archived versions of documents, etc.](#recording-links-to-full-text-andor-archived-versions-of-documents-etc)
+	- [Different licenses for different versions of the content](#different-licenses-for-different-versions-of-the-content)
+	- ["Libre" vs "Gratis"](#libre-vs-gratis)
+	- [Recording third party archive arrangements](#recording-third-party-archive-arrangements)
+	- [Assigning and registering DOIs at acceptance](#assigning-and-registering-dois-at-acceptance)
+		- [Assigning and registering DOIs for manuscripts that the publisher *has* made avaialble online](#assigning-and-registering-dois-for-manuscripts-that-the-publisher-has-made-avaialble-online)
+		- [Assigning and registering DOIs for manuscripts that the publisher *has not yet* made available online](#assigning-and-registering-dois-for-manuscripts-that-the-publisher-has-not-yet-made-available-online)
+	- [Bonus points](#bonus-points)
+			- [Distributing standard bibliographic metadata](#distributing-standard-bibliographic-metadata)
+			- [Distributing references](#distributing-references)
+			- [CrossMark](#crossmark)
+			- [Abstracts](#abstracts)
+			- [ORCIDs](#orcids)
+	- [Frequently Asked Questions](#frequently-asked-questions)
+	- [XML Deposit Examples](#xml-deposit-examples)
+		- [Full Deposits](#full-deposits)
+		- [Partial Deposits](#partial-deposits)
+		- [Registerd Content Deposits](#registerd-content-deposits)
+
 
 
 ## Version History
@@ -401,3 +432,7 @@ one updating funding information, the other updating license information.
 - [Partial deposit of funding information without CrossMark](examples/partial-funders.xml)
 - [Partial deposit of license information without CrossMark](examples/partial-licenses.xml)
 - [Partial deposit of a CrossMark with license and funding information](examples/partial-crossmark.xml)
+
+### Registerd Content Deposits
+
+*coming soon*

From b0f917df18c032ab902bd1f967f0e2d32f80e409 Mon Sep 17 00:00:00 2001
From: rlammey 
Date: Thu, 29 Oct 2015 09:01:05 +0000
Subject: [PATCH 093/219] Update funder_kpi_metadata_best_practice.md

### Registered Content Deposits
---
 funder_kpi_metadata_best_practice.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/funder_kpi_metadata_best_practice.md b/funder_kpi_metadata_best_practice.md
index 1e72f93..c4167f7 100644
--- a/funder_kpi_metadata_best_practice.md
+++ b/funder_kpi_metadata_best_practice.md
@@ -31,7 +31,7 @@
 	- [XML Deposit Examples](#xml-deposit-examples)
 		- [Full Deposits](#full-deposits)
 		- [Partial Deposits](#partial-deposits)
-		- [Registerd Content Deposits](#registerd-content-deposits)
+		- [Registered Content Deposits](#registered-content-deposits)
 
 
 
@@ -433,6 +433,6 @@ one updating funding information, the other updating license information.
 - [Partial deposit of license information without CrossMark](examples/partial-licenses.xml)
 - [Partial deposit of a CrossMark with license and funding information](examples/partial-crossmark.xml)
 
-### Registerd Content Deposits
+### Registered Content Deposits
 
 *coming soon*

From dcb3c8e813e87a755fc3689454c311b2cb152ebc Mon Sep 17 00:00:00 2001
From: Karl Jonathan Ward 
Date: Fri, 30 Oct 2015 11:25:25 +0000
Subject: [PATCH 094/219] Deep paging cursors for /works resources

---
 rest_api.md | 19 ++++++++++++++++++-
 1 file changed, 18 insertions(+), 1 deletion(-)

diff --git a/rest_api.md b/rest_api.md
index 1c50985..a6d1115 100644
--- a/rest_api.md
+++ b/rest_api.md
@@ -29,6 +29,7 @@
 - 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
 
 ## Background
 
@@ -333,7 +334,23 @@ The maximum number rows you can ask for in one query is `1000`.
 The number of returned items is controlled by the `rows` parameter, but you can select the offset into the result list by using the `offset` parameter.  So, for example, to select the second set of 5 results (i.e. results 6 through 10), you would do the following:
 
     http://api.crossref.org/works?query=allen+renear&rows=5&offset=5
-    
+
+### Deep Paging with Cursors
+
+Using large `offset` values can result in extremely long response times. Offsets in the 100,000s and beyond will likely cause a timeout before the API is able to respond. An alternative to paging through very large result sets (even the whole corpus of DOIs) it to use the API's exposure of Solr's deep paging cursors. Any combination of query, filters and facets may be used with deep paging cursors. While `rows` may be specified along with `cursor`, `offset` and `sample` cannot be used. To use deep paging make a query as normal, but include the `cursor` parameter with a value of `*`. In this example we will page through all `journal-article` works from member `311`:
+
+    http://api.crossref.org/members/311/works?filter=type:journal-article&cursor=*
+
+A `next-cursor` field will be provided in the JSON response. To get the next page of results, pass the value of `next-cursor` as the `cursor` parameter:
+
+    http://api.crossref.org/members/311/works?filter=type:journal-article&cursor=AoE/CGh0dHA6Ly9keC5kb2kub3JnLzEwLjEwMDIvdGRtX2xpY2Vuc2VfMQ==
+ 
+Clients should check the number of returned items. If the number of returned items is fewer than the number of expected rows then the end of the result set has been reached. Using `next-cursor` beyond this point will result in responses with an empty items list.
+
+In the response a `next-cursor` field will be provided if there are further 
+
+The `cursor` parameter is available on all `/works` resources.
+
 ### Sample
 
 Being able to select random results is useful for both testing and sampling. You can use the `sample` parameter to retrieve random results. So, for example, the following select 10 random works:

From 8ad58f1e18fc0223cc0c8b7e2b7d92e963124a2c Mon Sep 17 00:00:00 2001
From: Karl Jonathan Ward 
Date: Fri, 30 Oct 2015 11:26:45 +0000
Subject: [PATCH 095/219] Tidy up deep paging section

---
 rest_api.md | 2 --
 1 file changed, 2 deletions(-)

diff --git a/rest_api.md b/rest_api.md
index a6d1115..264a559 100644
--- a/rest_api.md
+++ b/rest_api.md
@@ -347,8 +347,6 @@ A `next-cursor` field will be provided in the JSON response. To get the next pag
  
 Clients should check the number of returned items. If the number of returned items is fewer than the number of expected rows then the end of the result set has been reached. Using `next-cursor` beyond this point will result in responses with an empty items list.
 
-In the response a `next-cursor` field will be provided if there are further 
-
 The `cursor` parameter is available on all `/works` resources.
 
 ### Sample

From 95c4500401a6095c085c87a088ac328377d31f30 Mon Sep 17 00:00:00 2001
From: Geoffrey Bilder 
Date: Fri, 30 Oct 2015 12:03:27 +0000
Subject: [PATCH 096/219] Update rest_api.md

---
 rest_api.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/rest_api.md b/rest_api.md
index 264a559..67512ab 100644
--- a/rest_api.md
+++ b/rest_api.md
@@ -337,7 +337,7 @@ The number of returned items is controlled by the `rows` parameter, but you can
 
 ### Deep Paging with Cursors
 
-Using large `offset` values can result in extremely long response times. Offsets in the 100,000s and beyond will likely cause a timeout before the API is able to respond. An alternative to paging through very large result sets (even the whole corpus of DOIs) it to use the API's exposure of Solr's deep paging cursors. Any combination of query, filters and facets may be used with deep paging cursors. While `rows` may be specified along with `cursor`, `offset` and `sample` cannot be used. To use deep paging make a query as normal, but include the `cursor` parameter with a value of `*`. In this example we will page through all `journal-article` works from member `311`:
+Using large `offset` values can result in extremely long response times. Offsets in the 100,000s and beyond will likely cause a timeout before the API is able to respond. An alternative to paging through very large result sets (like a corpus used for text and data mining) it to use the API's exposure of Solr's deep paging cursors. Any combination of query, filters and facets may be used with deep paging cursors. While `rows` may be specified along with `cursor`, `offset` and `sample` cannot be used. To use deep paging make a query as normal, but include the `cursor` parameter with a value of `*`. In this example we will page through all `journal-article` works from member `311`:
 
     http://api.crossref.org/members/311/works?filter=type:journal-article&cursor=*
 

From ba5c8e3bc410facb6d2ae6095f417f4a583cd31b Mon Sep 17 00:00:00 2001
From: Geoffrey Bilder 
Date: Thu, 5 Nov 2015 06:22:06 -0800
Subject: [PATCH 097/219] Update funder_kpi_metadata_best_practice.md

---
 funder_kpi_metadata_best_practice.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/funder_kpi_metadata_best_practice.md b/funder_kpi_metadata_best_practice.md
index c4167f7..7132530 100644
--- a/funder_kpi_metadata_best_practice.md
+++ b/funder_kpi_metadata_best_practice.md
@@ -294,7 +294,7 @@ CrossRef maintains a vocabulary of archive locations within the CrossRef deposit
 
 Funders and institutions would like to be notified of impending publications as early as possible. Some mandates, like the [one issued by HEFCE](http://www.hefce.ac.uk/pubs/year/2015/CL,202015/), even require that institutional repositories be notified of an impending relevant publication as soon as the manuscript is accepted- even if said manuscript has not yet been made available online.
 
-### Assigning and registering DOIs for manuscripts that the publisher *has* made avaialble online
+### Assigning and registering DOIs for manuscripts that the publisher *has* made available online
 
 Crossref has always supported the deposit of DOIs for accepted manuscripts __if__ said manuscripts have also been made available online. This is a common practice that goes under various names including “publish ahead of print,” “article in progress,” “article in press,” “online ahead of print,” “online first”, etc. Crossref rules state that in this situation, Crossref members:
 

From 21961b38ad4278e670937c250b7357f45ff07804 Mon Sep 17 00:00:00 2001
From: Geoffrey Bilder 
Date: Thu, 5 Nov 2015 06:47:24 -0800
Subject: [PATCH 098/219] Update funder_kpi_metadata_best_practice.md

---
 funder_kpi_metadata_best_practice.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/funder_kpi_metadata_best_practice.md b/funder_kpi_metadata_best_practice.md
index 7132530..e0a0231 100644
--- a/funder_kpi_metadata_best_practice.md
+++ b/funder_kpi_metadata_best_practice.md
@@ -338,7 +338,7 @@ Registered content DOI records:
 - __must__ include a DOI
 - __must__ include a date of acceptance
 - __must__ include the publisher name
-- __must__ must be replaced with appropriate full metadata using an appropriate schmea for the content type when the publisher makes the content publically available
+- __must__ must be replaced with appropriate full metadata using an appropriate schema for the content type when the publisher makes the content publically available
 - __should__ include an "intent to publish statement." If the publisher does not provide an "intent to publish statement" of their own, then Crossref will provide a default statement.
 - __may__ include a logo to diplay at the top of the landing page
 - __may__ include a custom "intent to publish statement."

From 11565f740fda716b4dbf46b0a87d3b43c75235e8 Mon Sep 17 00:00:00 2001
From: Geoffrey Bilder 
Date: Wed, 11 Nov 2015 23:11:27 +0100
Subject: [PATCH 099/219] add CNAME

---
 CNAME | 1 +
 1 file changed, 1 insertion(+)
 create mode 100644 CNAME

diff --git a/CNAME b/CNAME
new file mode 100644
index 0000000..c52642b
--- /dev/null
+++ b/CNAME
@@ -0,0 +1 @@
+api.crossref.org

From e01fef62b9f08d41b81e34f7879601102412e290 Mon Sep 17 00:00:00 2001
From: Geoffrey Bilder 
Date: Wed, 11 Nov 2015 23:13:10 +0100
Subject: [PATCH 100/219] remove CNAME

---
 CNAME | 1 -
 1 file changed, 1 deletion(-)
 delete mode 100644 CNAME

diff --git a/CNAME b/CNAME
deleted file mode 100644
index c52642b..0000000
--- a/CNAME
+++ /dev/null
@@ -1 +0,0 @@
-api.crossref.org

From 3b28f7163cf02d13b9c277f74e43b699fc2dc2d1 Mon Sep 17 00:00:00 2001
From: Karl Jonathan Ward 
Date: Mon, 14 Dec 2015 13:04:39 +0000
Subject: [PATCH 101/219] Correct archive filter example

Fix for #86.
---
 rest_api.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/rest_api.md b/rest_api.md
index 67512ab..88901a2 100644
--- a/rest_api.md
+++ b/rest_api.md
@@ -378,9 +378,9 @@ Note that when you use the `sample` parameter, the `rows` and `offset` parameter
 
 Note that the filters for license URL and maximum license embargo period (license.url and license.delay) combine to filter each document's metadata for a license with both of these properties.
 
-**All works where the archive partner listed = 'LOCKSS'**
+**All works where the archive partner listed = 'CLOCKSS'**
 
-    http://api.crossref.org/works?filter?archive=LOCKSS
+    http://api.crossref.org/works?filter=archive:CLOCKSS
     
 **All members with `hind` in their name (e.g. Hindawi)**
 

From e5abdbd5cc727901781fb779f61ffe3b607e758a Mon Sep 17 00:00:00 2001
From: Geoffrey Bilder 
Date: Tue, 22 Mar 2016 09:27:46 +0000
Subject: [PATCH 102/219] Update funder_kpi_metadata_best_practice.md

Updated mentions of "FunRef" to "Funding Data" and "Open Funder Registry" as appropriate. Updated "CrossRef" to "Crossref." Updated section on registered content to indicate impending finalization of process.
---
 funder_kpi_metadata_best_practice.md | 85 ++++++++++++++--------------
 1 file changed, 43 insertions(+), 42 deletions(-)

diff --git a/funder_kpi_metadata_best_practice.md b/funder_kpi_metadata_best_practice.md
index e0a0231..1474e38 100644
--- a/funder_kpi_metadata_best_practice.md
+++ b/funder_kpi_metadata_best_practice.md
@@ -49,6 +49,7 @@
 - v10: 2013-12-03, Updated `` element documentation to reflect latest NISO work. Added information about licensing CrossRef metadata to FAQ (hint, no license required for free APIs). Added labs email address. Changed formatting.
 - v11: 2013-12-11, Added third party archive arrangements section. Updated examples to include archive locations.
 - v12: 2015-11-27, Revisions to describe deposit workflow to support alerting funders/instituions when content has been "accepted". Pointers to latest schemas. General cleanup.
+- v13: 2016-03-22, Updated mentions of "FunRef" to "Funding Data" and "Open Funder Registry" as appropriate. Updated "CrossRef" to "Crossref." Updated section on registered content to indicate impending finalization of process. 
 
 ## Contact info
 
@@ -60,7 +61,7 @@ If you encounter problems with the API or the documentation, please report them
 
 Funders are increasingly setting mandates around publications that result from research they have funded. The mandates include specifications about licenses, embargoes, and notifications of publication acceptance and/or publication. This poses logistical problems for all the parties involved. Funders will need a way to track outputs from thousands of publishers. Publishers will need a standard and efficient way to demonstrate conformance to the mandates. All the stakeholders in the process (funders, publishers, institutions and researchers) will span disciplines, institutions, geographies and jurisdictions. Crossref was setup specifically to deal with these sorts of multiple bilateral relationships.
 
-Crossref has extended its metadata schemas and Application Programming Interfaces (APIs) to enable funding agencies, institutions and publishers to use CrossRef as a metadata source that can be used to track research that is subject to these mandates and to ensure that said research is being disseminated according to the requirements of the mandates.
+Crossref has extended its metadata schemas and Application Programming Interfaces (APIs) to enable funding agencies, institutions and publishers to use Crossref as a metadata source that can be used to track research that is subject to these mandates and to ensure that said research is being disseminated according to the requirements of the mandates.
 
 Funders, institutions, publishers and third parties providing research information management tools (e.g. *[CHORUS](http://publishers.org/press/107/)*, *[SHARE](http://www.arl.org/news/arl-news/2773-shared-access-research-ecosystem-proposed-by-aau-aplu-arl)*,*[Symplectic](http://symplectic.co.uk)* can make use of Crossref APIs and metadata in order to identify:
 
@@ -76,7 +77,7 @@ Funders, institutions, publishers and third parties providing research informati
 
 This data can be propagated by publisher at any time after publication acceptance- according to the requirements of the relevant mandates.
 
-The CrossRef extended APIs, of course, will only work if publishers supply the appropriate metadata and follow the specified metadata deposit workflows. This document outlines the metadata that publishers will need to provide and the metadata deposit workflows they will need to support in order to advertise their conformance to funder mandates.
+The Crossref extended APIs, of course, will only work if publishers supply the appropriate metadata and follow the specified metadata deposit workflows. This document outlines the metadata that publishers will need to provide and the metadata deposit workflows they will need to support in order to advertise their conformance to funder mandates.
 
 ## Conventions
 
@@ -92,24 +93,24 @@ Although this document is not an RFC, it will follow the conventions of __[rfc21
 
 In order to advertise conformance to funder mandates, Crossref members:
 
-- __must__ record funder information in their CrossRef deposits  
-- __must__ deposit the FundRef funder identifiers corresponding to their funder names where these exist in the FundRef Registry
+- __must__ record funder information in their Crossref deposits  
+- __must__ deposit the funder identifiers corresponding to their funder names where these exist in the Open Funder Registry
 -  __should__ record award numbers when possible.
-- __should__ record funding information within CrossMark records __if__ they are either implementing CrossMark or are planning to implement CrossMark within the next two years.
+- __should__ record Funding Data within CrossMark records __if__ they are either implementing CrossMark or are planning to implement CrossMark within the next two years.
 - __should__ record licensing information if they have it by means of a URI specifying the license under which the publication is made.
 - If publishers do not have licensing information, they __should__ record a placeholder URI and fill in the target of the URI once they have agreed on licensing information.
 - __should__ record full text links to the readable version(s) of the document. This may include different resources for the Version of Record (VOR) and Author Accepted Manuscript (AM).
 - __should__ record full text links to representations of the document that are made available for TDM. These may be the same or different to the "readable" versions of the document pointed to above.
 - Where they are recording multiple versions of the document (e.g. AM & VOR), the publisher __should__ map licensing information to the specific resource versions.
-- __should__ record full text links to archived versions of the document identified by the CrossRef DOI.
-- __should__ record archive arrangements made with third party archiving organizations where the document identified by the CrossRef DOI is archived with the third party.
+- __should__ record full text links to archived versions of the document identified by the Crossref DOI.
+- __should__ record archive arrangements made with third party archiving organizations where the document identified by the Crossref DOI is archived with the third party.
 
-In order to enhance the utility of CrossRef metadata to funders and in order to enable more sophisticated funder/publisher KPIs, Crossref members:
+In order to enhance the utility of Crossref metadata to funders and in order to enable more sophisticated funder/publisher KPIs, Crossref members:
 
 - __should__ consider participating in CrossMark in order to record updates, errata, corrigenda,retractions and withdrawals.
-- __should__ consider depositing abstracts using CrossRef's JATS abstract element support.
+- __should__ consider depositing abstracts using Crossref's JATS abstract element support.
 - __should__ consider collecting and depositing ORCIDs for publication authors.
-- __should__ consider making the bibliographic metadata and references for documents resulting from agency funding maximally available by overriding CrossRef opt-outs using the `` and `` elements.
+- __should__ consider making the bibliographic metadata and references for documents resulting from agency funding maximally available by overriding Crossref opt-outs using the `` and `` elements.
 
 In order to alert funders of relevant publications as soon as possible, Crossref members:
 
@@ -117,23 +118,23 @@ In order to alert funders of relevant publications as soon as possible, Crossref
 
 ## Funding information
 
-CrossRef supports the recording of funding information for a publication via its [FundRef](http://www.crossref.org/fundref/) program. FundRef defines an open, standard [registry of funder names and funder identifiers](http://www.crossref.org/fundref/fundref_registry.html) that can be used in order to increase the accuracy of the funding information recorded. Although FundRef supports recording award_numbers along with funder identifiers, FundRef does __not__ define standards for recording award numbers as practice varies greatly across funders.
+Crossref supports the recording of funding information for a publication via its [Funding Data](http://www.crossref.org/fundingdata/index.html) program. The Open Funder Registry defines an open, standard [registry of funder names and funder identifiers](http://www.crossref.org/fundingdata/registry.html) that can be used in order to increase the accuracy of the funding information recorded. Although Funding Data supports recording award_numbers along with funder identifiers, Crossref does __not__ define standards for recording award numbers as practice varies greatly across funders.
 
-To support funder KPIs, members __must__ deposits funder metadata using the specifications defined for the FundRef program. Specifically, when depositing metadata you:
+To support funder KPIs, members __must__ deposits funder metadata using the specifications defined for the Funder Data program. Specifically, when depositing metadata you:
 
 
 1. __must__ include funder information.
-2. __must not__ deposit your funder names without at least trying to map them to FundRef identifiers in the FundRef registry. Depositing funder names that are included in the FundRef registry, but without their respective FundRef Funder Identifiers, will pollute the FundRef metadata and lower the value of the service for all participants. Note that the KPI APIs will only work for Funder metadata that includes FundRef Funder Identifiers.
-3. __should__ include award numbers in FundRef metadata when possible. Although the standard KPI API does not make direct use of award numbers, individual agencies may be able to make use of included award numbers where found.
-4. __should__ deposit FundRef data as part of a CrossMark record if you (the publisher) already are (or *are planning* to become) a participant in CrossMark. There are two reasons for this: First, it ensures that the Funder Metadata is available __both__ in a standard machine readable format __AND__ via a standard UI for readers. Second, it ensures that the Funder metadata is made maximally reusable via a CC Zero license waiver. Note that publishers do not __need__ to have implemented CrossMark yet to deposit Funder metadata via CrossMark. We expect that publishers may take a year or more before they have fully implemented all of CrossMark's features.
+2. __must not__ deposit your funder names without at least trying to map them toidentifiers in the Open Funder Registry. Depositing funder names that are included in the Open Funder Registry registry, but without their respective funder identifiers, will pollute the Funder Data and lower the value of the service for all participants. Note that the KPI APIs will only work for Funder Data that includes Open Funder Registry Identifiers.
+3. __should__ include award numbers in Funder Data when possible. Although the standard KPI API does not make direct use of award numbers, individual agencies may be able to make use of included award numbers where found.
+4. __should__ deposit Funder Data as part of a CrossMark record if you (the publisher) already are (or *are planning* to become) a participant in CrossMark. There are two reasons for this: First, it ensures that the Funder Data is available __both__ in a standard machine readable format __AND__ via a standard UI for readers. Second, it ensures that the Funder Data is made maximally reusable via a CC Zero license waiver. Note that publishers do not __need__ to have implemented CrossMark yet to deposit Funder metadata via CrossMark. We expect that publishers may take a year or more before they have fully implemented all of CrossMark's features.
 
-See CrossRef's Help pages for [Technical details on depositing FundRef metadata.](http://help.crossref.org/#fundref)
+See Crossref's Help pages for [Technical details on depositing Funder Data.](http://help.crossref.org/#fundref)
 
 ## License information
 
-One of the main drivers for the FunRef KPI API is that many funders are required to report on the public availability of the results and publications arising from funder-financed research. Funders are therefor interested in understanding how publications related to funded research are licensed.
+One of the main drivers for the Funder Data KPI API is that many funders are required to report on the public availability of the results and publications arising from funder-financed research. Funders are therefor interested in understanding how publications related to funded research are licensed.
 
-To deposit license information, publishers __must__ use the `` element. The value of the `` element __must__ be a stable HTTP URI which points to a human-readable document that either includes (or guides the reader to) any copyright and/or licensing information related to the CrossRef DOI of the content. The URI __must__ point either to a location on the publisher's site or to the stable location of any well-known licenses such as those of the Creative Commons.  
+To deposit license information, publishers __must__ use the `` element. The value of the `` element __must__ be a stable HTTP URI which points to a human-readable document that either includes (or guides the reader to) any copyright and/or licensing information related to the Crossref DOI of the content. The URI __must__ point either to a location on the publisher's site or to the stable location of any well-known licenses such as those of the Creative Commons.  
 
 Note that it is entirely acceptable to record a `` URI as a "placeholder." If you are still working out specific licensing terms, the URI you record __should__ point to a blank page or even a simple re-assertion of the document's copyright. There is a big difference between recording at least some `` URI and recording no `` URI at all. The former indicates an intent to eventually clarify licensing information, whereas the latter indicates that the licensing information is likely to remain ambiguous.
 
@@ -177,7 +178,7 @@ Note that there is __no__ corresponding `end_date` attribute for the `` element at the time the license changes? By recording that another license takes effect in the future, you are informing the consumer of the metadata that the current restricted license is only for the embargo period. In short, you are recording the __intent__ to change the license when the embargo is done. Furthermore, providing additional metadata for a current publication at some future date is an additional chore for the publisher that might well be overlooked.
 
-In the above examples, the `` element is unqualified and should therefor be considered to apply to the content pointed to by any `` URIs included in the CrossRef metadata. The CrossRef metadata schema supports recording different license for different versions of the resource and this will be discussed below. However, first let's look at at the role the `` element plays in providing funding agency KPIs.
+In the above examples, the `` element is unqualified and should therefor be considered to apply to the content pointed to by any `` URIs included in the Crossref metadata. The Crossref metadata schema supports recording different license for different versions of the resource and this will be discussed below. However, first let's look at at the role the `` element plays in providing funding agency KPIs.
 
 ## Recording links to full text and/or archived versions of documents, etc.
 
@@ -185,23 +186,23 @@ Funders are not just interested in reporting on the licensing terms of publicati
 
 To this end, publishers need to be able to record links to the full text of the content to which a DOI refers. Additionally, publishers will want to offer different versions (e.g. AM or VOR) and different representations (e.g. PDF for viewing, XML for TDM, etc.) of the content tailored for specific applications.
 
-The `` element in CrossRef metadata is most often used to record an HTTP URI pointing at the publisher's landing page for the publication identified by the CrossRef DOI in question. However, the CrossRef schema has long supported the recording of multiple `` elements in order to enable, for example:
+The `` element in Crossref metadata is most often used to record an HTTP URI pointing at the publisher's landing page for the publication identified by the Crossref DOI in question. However, the Crossref schema has long supported the recording of multiple `` elements in order to enable, for example:
 
 - Multiple resolution
 - Search engine indexing
 - CrossCheck indexing
 
-CrossRef has extended the ability to record multiple `` elements in order to allow the recording of URIs which point to the full text of content identified by the CrossRef DOI. The publisher can record multiple representations of the full text (e.g. PDF, XML, plain text) using the new `mime_type` attribute and then, through their access control systems, control who is able to reach which representation and under which conditions.
+Crossref has extended the ability to record multiple `` elements in order to allow the recording of URIs which point to the full text of content identified by the Crossref DOI. The publisher can record multiple representations of the full text (e.g. PDF, XML, plain text) using the new `mime_type` attribute and then, through their access control systems, control who is able to reach which representation and under which conditions.
 
 Note that, by recording a `` that points to the full text, you are not necessarily guaranteeing that the URI will be accessible
 
 Note also that the publisher could theoretically choose only to deposit `` elements for full text representations once an embargo has ended. However, this approach may prove fraught, as any mistakes or delays in the redeposit process might lead the funding agency to believe that the publisher has not made the relevant content accessible at the end of the embargo period.
 
-Further detail on using the `` element for recording links to full text can be found on the [Prospect support site](http://prospectsupport.labs.crossref.org/full-text-uris-technical-details/) and in the CrossRef deposit schema documentation for the [ `` ](http://www.crossref.org/schema/documentation/4.3.4/4.3.4.html#collection) and [ `` ](http://www.crossref.org/schema/documentation/4.3.4/4.3.4.html#resource) elements.
+Further detail on using the `` element for recording links to full text can be found on the [Prospect support site](http://prospectsupport.labs.crossref.org/full-text-uris-technical-details/) and in the Crossref deposit schema documentation for the [ `` ](http://www.crossref.org/schema/documentation/4.3.4/4.3.4.html#collection) and [ `` ](http://www.crossref.org/schema/documentation/4.3.4/4.3.4.html#resource) elements.
 
 ## Different licenses for different versions of the content
 
-Some publishers may want to record different licenses for different versions of the `` element recorded in CrossRef metadata. For example, one `` element may point to a URI intended for subscribed readers, while another `` element may point to a version of the document intended for Text and Data Mining (TDM) applications. Similarly, a publisher may choose to apply one license to the "Author Accepted Manuscript" (AM) and another to the "Version of Record" (VOR).
+Some publishers may want to record different licenses for different versions of the `` element recorded in Crossref metadata. For example, one `` element may point to a URI intended for subscribed readers, while another `` element may point to a version of the document intended for Text and Data Mining (TDM) applications. Similarly, a publisher may choose to apply one license to the "Author Accepted Manuscript" (AM) and another to the "Version of Record" (VOR).
 
 To accommodate these scenarios, the `` element supports an `applies_to` element. Similarly, the `` element has been extended to support a `content_version` attribute. Publishers can use these element/attribute combinations to apply specific licenses to specific versions of the resource. For example, to indicate the "VOR" version of a document is licensed under a proprietary license, but that the "AM" version of the same document is licensed under an open license, the `` and `` elements could be combined like this:
 
@@ -211,7 +212,7 @@ To accommodate these scenarios, the `` element supports an `applies
 
     http://creativecommons.org/licenses/by/3.0/deed.en_US
 
-    
+    
 
     http://www.psychoceramics.org/fulltext/vor/10.5555/12345678
 
@@ -231,7 +232,7 @@ The `` and `` elements along with their respective `start
 
     http://www.psychoceramics.org/nc_tdm_license.html
 
-    
+    
 
     http://www.psychoceramics.org/fulltext/vor/10.5555/12345678
 
@@ -241,14 +242,14 @@ The `` and `` elements along with their respective `start
 
     http://www.psychoceramics.org/fulltext/tdm/10.5555/12345678.xml
 
-Detailed information on recording licensing information in CrossRef metadata can be found in the CrossRef schema documentation for the [ `` ](http://www.crossref.org/schema/documentation/4.3.4/AccessIndicators_xsd.html#license_ref) element.
+Detailed information on recording licensing information in Crossref metadata can be found in the Crossref schema documentation for the [ `` ](http://www.crossref.org/schema/documentation/4.3.4/AccessIndicators_xsd.html#license_ref) element.
 
 ## "Libre" vs "Gratis"
 
 The license information recorded in the `` element can tell you what you are allowed to do with the resources the licenses point to, but they do not say anything about whether or not there is a monetary charge involved.
-In order to allow a publisher to record whether access to the content requires payment, CrossRef supports a new `` element. The `` element is an empty element. It can include two attributes, a `start_date` and an `end_date`. The `` elements works as follows:
+In order to allow a publisher to record whether access to the content requires payment, Crossref supports a new `` element. The `` element is an empty element. It can include two attributes, a `start_date` and an `end_date`. The `` elements works as follows:
 
- - The presence of a  element in CrossRef metadata __should_ be interpreted to mean that the full text content pointed to by the  DOI resource is available "gratis" during the time period specified by the start_date and end_date attributes.
+ - The presence of a  element in Crossref metadata __should_ be interpreted to mean that the full text content pointed to by the  DOI resource is available "gratis" during the time period specified by the start_date and end_date attributes.
  - If the  element only includes a `start_date` attribute, then the element __should__ be interpreted to mean that the content pointed to by the DOI resource will be made gratis from `start_date` on.
  - If the  element only includes a `end_date` attribute, then the element __should__ be interpreted to mean that the content pointed to by the DOI resource will be made gratis from the publication date to and including the `end_date`.
  - If the  element has __no__ `start_date` __or__ `end_date` attributes, then the element __should__ be interpreted to mean that the content pointed to by the DOI resource is available "gratis" from the date of publication on.
@@ -281,14 +282,14 @@ In order to allow a publisher to record whether access to the content requires p
 
 Funders may be concerned that publisher links to full-text content will become unavailable in exceptional circumstances. They may stipulate that content is archived with a third party archiving organization, and may even suggest a list of acceptable archive organizations with which documents should be archived.
 
-Publishers can record the archive arrangement or archive intention of a document using the `` element in CrossRef deposit metadata. Any number of archive locations can be specified, for example a document may be archived with both `Portico` and `CLOCKSS`:
+Publishers can record the archive arrangement or archive intention of a document using the `` element in Crossref deposit metadata. Any number of archive locations can be specified, for example a document may be archived with both `Portico` and `CLOCKSS`:
 
     
 	  
 	  
     
 
-CrossRef maintains a vocabulary of archive locations within the CrossRef deposit schema. The latest list of possible archive location values can be found in the documentation for the [ `` element ](http://www.crossref.org/help/schema_doc/4.3.6/4.3.6.html).
+Crossref maintains a vocabulary of archive locations within the Crossref deposit schema. The latest list of possible archive location values can be found in the documentation for the [ `` element ](http://www.crossref.org/help/schema_doc/4.3.6/4.3.6.html).
 
 ## Assigning and registering DOIs at acceptance
 
@@ -306,7 +307,7 @@ Crossref has always supported the deposit of DOIs for accepted manuscripts __if_
 
 ### Assigning and registering DOIs for manuscripts that the publisher *has not yet* made available online
 
-*(Please note that this section includes a draft recommendation which have not yet been ratified by our members or implemented. We are soliciting feedback on this section of the  document.)*
+*(Please note that this section includes a draft rules and guidelines. These are being finalised and this section will be updated accordingly)*
 
 Crossref will support a new mechanism and workflow to support the registration of DOIs for accepted manuscripts __before__ they are made publicly available online. This feature can be used by publishers as a mechanism for informing funders and institutions of impending publications. To use this, publishers will deposit a special type of Crossref record called "registered content."
 
@@ -323,7 +324,7 @@ Publishers will able to apply limited customizations to the landing page. These
 - the display of all provided optional extra metadata such as funder identifiers, ORCID ids, license information, etc.
 - a CrossMark, to handle situations in which a publisher rescinds an acceptance.
 
-If the publisher provides metadata beyond that required, it will be displayed on the landing page below the "intent to publish" statement. "Registered content" records will also be made available through the CrossRef REST API and through Crossref metadata search.
+If the publisher provides metadata beyond that required, it will be displayed on the landing page below the "intent to publish" statement. "Registered content" records will also be made available through the Crossref REST API and through Crossref metadata search.
 
 By having Crossref control the landing page for "registered content" we can ensure that:
 
@@ -343,7 +344,7 @@ Registered content DOI records:
 - __may__ include a logo to diplay at the top of the landing page
 - __may__ include a custom "intent to publish statement."
 - __should__ include funder information
-- __should__ include FundRef funder identifiers corresponding to their funder names where these exist in the FundRef Registry
+- __should__ include Open Funder Registry funder identifiers corresponding to their funder names where these exist in the registry
 - __should__ include ORCIDs
 - __should__ include license information
 - __should__ author affiliation information
@@ -354,38 +355,38 @@ The "registered content" type is specifically designed for publishers who want t
 
 ## Bonus points
 
-The more metadata that publishers record for publications arising from agency funded research, the more useful that metadata will be to said agencies and the more value they will see from publishers. Where as the above sections details metadata elements that agencies will __expect__ in order to be able to compile basic KPIs and offer portal services, additional metadata will allow agencies to create even more sophisticated KPIs and services. As such, publishers should seriously consider depositing the following additional metadata elements in their CrossRef deposits.
+The more metadata that publishers record for publications arising from agency funded research, the more useful that metadata will be to said agencies and the more value they will see from publishers. Where as the above sections details metadata elements that agencies will __expect__ in order to be able to compile basic KPIs and offer portal services, additional metadata will allow agencies to create even more sophisticated KPIs and services. As such, publishers should seriously consider depositing the following additional metadata elements in their Crossref deposits.
 
 #### Distributing standard bibliographic metadata
 
-Metadata deposited to CrossRef is made available freely via numerous CrossRef query APIs. However all deposited metadata is subject to opt-outs in the case of bulk distribution APIs and data dumps. In order to make sure that bibliographic metadata for publications arising from agency funding is maximally available, publishers __should__ consider setting the value of the `` element for DOIs to `any`.  Further details can be found in [CrossRef's schema documentation for the `` element.](http://www.crossref.org/schema/documentation/4.3.4/NO_NAMESPACE.html#metadata_distribution_opts.att_metadata_distribution_opts)
+Metadata deposited to Crossref is made available freely via numerous Crossref query APIs. However all deposited metadata is subject to opt-outs in the case of bulk distribution APIs and data dumps. In order to make sure that bibliographic metadata for publications arising from agency funding is maximally available, publishers __should__ consider setting the value of the `` element for DOIs to `any`.  Further details can be found in [Crossref's schema documentation for the `` element.](http://www.crossref.org/schema/documentation/4.3.4/NO_NAMESPACE.html#metadata_distribution_opts.att_metadata_distribution_opts)
 
 #### Distributing references
 
-References made in publications arising from agency funding can provide agencies with an overview of what literature is considered important in the fields that they fund. Many publishers deposit references to CrossRef as part of their participation CrossRef's [CitedBy](http://www.crossref.org/citedby/index.html) service. However, participation in CitedBy does not automatically make references available via CrossRef's standard APIs. In order for publishers to distribute references along with standard bibliographic metadata, publishers need to set the `` element to `any` for each DOI deposit where they want to make references openly available. By setting this element, references for the DOI will be distributed without restriction through all of CrossRefs APIs and bulk metadata dumps. Further details can be found in [CrossRef's schema documentation for the `` element.](http://www.crossref.org/schema/documentation/4.3.4/4.3.4.html#reference_distribution_opts.att)
+References made in publications arising from agency funding can provide agencies with an overview of what literature is considered important in the fields that they fund. Many publishers deposit references to Crossref as part of their participation Crossref's [CitedBy](http://www.crossref.org/citedby/index.html) service. However, participation in CitedBy does not automatically make references available via Crossref's standard APIs. In order for publishers to distribute references along with standard bibliographic metadata, publishers need to set the `` element to `any` for each DOI deposit where they want to make references openly available. By setting this element, references for the DOI will be distributed without restriction through all of Crossrefs APIs and bulk metadata dumps. Further details can be found in [Crossref's schema documentation for the `` element.](http://www.crossref.org/schema/documentation/4.3.4/4.3.4.html#reference_distribution_opts.att)
 
 #### CrossMark
 
 [CrossMark](http://www.crossref.org/crossmark/) provides a standard mechanism for alerting researchers to updates to published documents- including corrections, errata, corrigenda retractions and withdrawals. Use of the CrossMark service sends a signal to researchers and agencies that publishers are committed to maintaining the integrity of the scholarly record.
 
-Additionally, CrossMark also provides a standard, cross-publisher, user interface that researchers can use to view FundRef information and licensing information. This user interface works both from publisher landing pages and from published PDFs. More information can be found on the [CrossMark support site](http://crossmarksupport.crossref.org/)
+Additionally, CrossMark also provides a standard, cross-publisher, user interface that researchers can use to view Funder Data and licensing information. This user interface works both from publisher landing pages and from published PDFs. More information can be found on the [CrossMark support site](http://crossmarksupport.crossref.org/)
 
 #### Abstracts
 
 Many funding agencies are interested in building custom portals that highlight agency-funded research. In order to provide users of these portals with the best experience, agencies will want, where possible, to display abstracts of publications along with their standard bibliographic metadata.
 
-CrossRef supports the deposit of abstracts conforming to the [JATS](http://jats.nlm.nih.gov/) abstract element. Further details can be found in the [CrossRef Schema Documentation of the `` element](http://www.crossref.org/schema/documentation/4.3.4/JATS1.html#abstract).
+Crossref supports the deposit of abstracts conforming to the [JATS](http://jats.nlm.nih.gov/) abstract element. Further details can be found in the [Crossref Schema Documentation of the `` element](http://www.crossref.org/schema/documentation/4.3.4/JATS1.html#abstract).
 
 #### ORCIDs
 
-[ORCID](http://www.orcid.org/)s are unique identifiers for researchers. CrossRef supports the deposit of ORCIDs for authors. The presence of ORCIDs in CrossRef metadata will, in turn, allow agencies to tie agency funded research publications directly to researchers. Widespread use of ORCIDs in CrossRef deposits could even let agencies start to develop publication KPIs for researchers that they fund. Further details on CrossRef's ORCID support can be found in the [CrossRef Schema Documentation of the `` element](http://www.crossref.org/schema/documentation/4.3.4/4.3.4.html#ORCID)
+[ORCID](http://www.orcid.org/)s are unique identifiers for researchers. Crossref supports the deposit of ORCIDs for authors. The presence of ORCIDs in Crossref metadata will, in turn, allow agencies to tie agency funded research publications directly to researchers. Widespread use of ORCIDs in Crossref deposits could even let agencies start to develop publication KPIs for researchers that they fund. Further details on Crossref's ORCID support can be found in the [Crossref Schema Documentation of the `` element](http://www.crossref.org/schema/documentation/4.3.4/4.3.4.html#ORCID)
 
 
 ## Frequently Asked Questions
 
-**Q:** What license applies to the metadata retrieved by the [CrossRef APIs to support key performance indicators (KPIs) for funding agencies](funder_kpi_api.html)?
+**Q:** What license applies to the metadata retrieved by the [Crossref APIs to support key performance indicators (KPIs) for funding agencies](funder_kpi_api.html)?
 
    
-**A:** 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/).
+**A:** 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/).
 
 **Q:** What does it mean if a `` element has no `start_date` attribute?
 
    
@@ -418,7 +419,7 @@ Full deposits use the [standard deposit schema](http://www.crossref.org/schema/d
 
 Partial deposits use the [resource deposit schema](http://doi.crossref.org/schemas/doi_resources4.3.2.xsd).
 
-Partial deposits update only part of a DOI's metadata. In the CrossRef help system
+Partial deposits update only part of a DOI's metadata. In the Crossref help system
 they are referred to as **resource deposits**, but it is not just resources that can
 be provided as a partial deposit. Licenses, funding information and CrossMarks can also
 be provided as partial deposits.

From e4ebd9317da8921e7766e7bc5b8472c0c1de6f5b Mon Sep 17 00:00:00 2001
From: Geoffrey Bilder 
Date: Mon, 9 May 2016 11:52:18 -0400
Subject: [PATCH 103/219] added link to source of category labels

---
 rest_api.md | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/rest_api.md b/rest_api.md
index 88901a2..21fcd56 100644
--- a/rest_api.md
+++ b/rest_api.md
@@ -30,6 +30,7 @@
 - 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
+- v28, 2016-05-09, Added link to source of category lables
 
 ## Background
 
@@ -263,7 +264,7 @@ Filters allow you to narrow queries. All filter results are lists.  The followin
 | `has-update-policy` | | metadata for records that include a link to an editorial update policy |
 | `container-title` | | metadata for records with a publication title exactly with an exact match |
 | `publisher-name` | | metadata for records with an exact matching publisher name |
-| `category-name` | | metadata for records with an exact matching category label |
+| `category-name` | | metadata for records with an exact matching category label. Category labels come from [this list](https://www.elsevier.com/solutions/scopus/content) published by Scopus |
 | `type-name` | | metadata for records with an exacty matching type label |
 | `award.number` | `{award_number}` | metadata for records with a matching award nunber. Optionally combine with `award.funder` |
 | `award.funder` | `{funder doi or id}` | metadata for records with an award with matching funder. Optionally combine with `award.number` |

From 9fe3618968f5802aba712e9742fcc84fd407a31f Mon Sep 17 00:00:00 2001
From: Karl Jonathan Ward 
Date: Tue, 24 May 2016 21:38:47 +0100
Subject: [PATCH 104/219] Describe field queries and list those on /works

---
 rest_api.md | 35 ++++++++++++++++++++++++++++++++---
 1 file changed, 32 insertions(+), 3 deletions(-)

diff --git a/rest_api.md b/rest_api.md
index 21fcd56..e7c62c7 100644
--- a/rest_api.md
+++ b/rest_api.md
@@ -31,6 +31,7 @@
 - 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
 - v28, 2016-05-09, Added link to source of category lables
+- v29, 2016-05-24, Added field queries
 
 ## Background
 
@@ -193,12 +194,40 @@ Multiple filters can be specified by separating name:value pairs with a comma:
 
 ## Queries
 
-Queries support a subset of [DisMax](https://wiki.apache.org/solr/DisMax), so, for example you can refine queries as follows.
+Queries support a subset of [DisMax](https://wiki.apache.org/solr/DisMax), so, for example you 
+can refine queries as follows.
 
-**Works that include "renear" but not "ontologies"**
+Works that include "renear" but not "ontologies":
 
     http://api.crossref.org/works?query=renear+-ontologies
-    
+	
+## Field Queries
+
+Field queries are available on some routes and allow for queries that match only particular fields
+of metadata. For example, this query matches records that contain the tokens `richard` or `feynman` (or both)
+in any author field:
+
+    http://api.crossref.org/works?query.author=richard+feynman
+	
+Field queries can be combined with the general `query` paramter and each other. Each query parameter
+is `ANDed` with the others:
+
+    http://api.crossref.org/works?query.title=room+at+the+bottom&query.author=richard+feynman
+	
+### `/works` Field Queries
+
+These field queries are available on the `/works` route:
+
+| Field query parameter | Description |
+|-|-|
+| `query.title` | Query `title` and `subtitle` |
+| `query.container-title` | Query `container-title` aka. publication name |
+| `query.author` | Query author first and given names |
+| `query.editor` | Query editor first and given names |
+| `query.chair` | Query chair first and given names |
+| `query.translator` | Query translator first and given names |
+| `query.contributor` | Query author, editor, chair and translator first and given names |
+
 ## Sorting
 
 Results from a listy response can be sorted by applying the `sort` and `order` parameters. Order

From 92a98c058315d7258423d101f2a6d7382883d215 Mon Sep 17 00:00:00 2001
From: Karl Jonathan Ward 
Date: Tue, 24 May 2016 21:41:25 +0100
Subject: [PATCH 105/219] Fix formatting of /works field query table

---
 rest_api.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/rest_api.md b/rest_api.md
index e7c62c7..b572d49 100644
--- a/rest_api.md
+++ b/rest_api.md
@@ -210,7 +210,7 @@ in any author field:
     http://api.crossref.org/works?query.author=richard+feynman
 	
 Field queries can be combined with the general `query` paramter and each other. Each query parameter
-is `ANDed` with the others:
+is ANDed with the others:
 
     http://api.crossref.org/works?query.title=room+at+the+bottom&query.author=richard+feynman
 	
@@ -219,7 +219,7 @@ is `ANDed` with the others:
 These field queries are available on the `/works` route:
 
 | Field query parameter | Description |
-|-|-|
+|-----------------------|-------------|
 | `query.title` | Query `title` and `subtitle` |
 | `query.container-title` | Query `container-title` aka. publication name |
 | `query.author` | Query author first and given names |

From d810bd3588ab7fd399b9c5dd428bffad93819aec Mon Sep 17 00:00:00 2001
From: Karl Jonathan Ward 
Date: Thu, 26 May 2016 10:17:26 +0100
Subject: [PATCH 106/219] Fix broken link to old KPI document

---
 rest_api.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/rest_api.md b/rest_api.md
index b572d49..6c52af0 100644
--- a/rest_api.md
+++ b/rest_api.md
@@ -35,7 +35,7 @@
 
 ## Background
 
-See the document, [CrossRef metadata best practice to support key performance indicators (KPIs) for funding agencies](http://api.crossref.org/docs/funder_kpi_metadata_best_practice.html), for 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/rest_api.md), for background.
 
 ## Reporting issues
 

From 59068bd3fd7d8c5348d9b69f40e069cbc8c355de Mon Sep 17 00:00:00 2001
From: Karl Jonathan Ward 
Date: Thu, 26 May 2016 10:18:19 +0100
Subject: [PATCH 107/219] Put the right link in to old KPI document

---
 rest_api.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/rest_api.md b/rest_api.md
index 6c52af0..badddf5 100644
--- a/rest_api.md
+++ b/rest_api.md
@@ -35,7 +35,7 @@
 
 ## 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/rest_api.md), for 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.
 
 ## Reporting issues
 

From d472968163244f7f02299bebdbdcbb7a912df001 Mon Sep 17 00:00:00 2001
From: Karl Jonathan Ward 
Date: Mon, 11 Jul 2016 14:08:24 -0400
Subject: [PATCH 108/219] List of fields in /works JSON

---
 api_format.md | 125 ++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 125 insertions(+)
 create mode 100644 api_format.md

diff --git a/api_format.md b/api_format.md
new file mode 100644
index 0000000..756a24f
--- /dev/null
+++ b/api_format.md
@@ -0,0 +1,125 @@
+# Crossref Metadata API JSON Format
+
+## Versioning
+
+| Version | Release Date | Comments |
+|---------|--------------|----------|
+| v1 | 11th July 2016 | First documented version |
+
+## Work
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| publisher | String | Yes | Name of work's publisher |
+| title | Array of String | Yes | Work titles, including original language title and translated titles |
+| subtitle | Array of String | No | Work subtitles, including original language and translated |
+| container-title | Array of String | No |
+| reference-count | Number | Yes | Count of outbound references deposited with Crossref |
+| issue | String | No | Issue number of an article's journal |
+| volume | String | No | Volume number of an article's journal |
+| page | String | No | Pages numbers of an article within its journal |
+| source | String | Yes | Currently always `crossref` |
+| prefix | String | Yes | |
+| DOI | String | Yes | |
+| member | String | Yes | |
+| type | String | Yes | Enumeration, one of the type ids from `https://api.crossref.org/v1/types` |
+| created | Date | Yes | |
+| deposited | Date | Yes | |
+| indexed | Date | Yes | |
+| published-print | Date | No | |
+| published-online | Date | No | |
+| issued | Date | Yes | Eariest of published-print and published-online |
+| subject | Array of String | No | |
+| ISSN | Array of String | No | |
+| ISBN | Array of String | No | |
+| archive | Array of String | No | |
+| license | Array of License | No | |
+| funder | Array of Funder | No | |
+| assertion | Array of Assertion | No | |
+| author | Array of Author | No | |
+| editor | Array of Editor | No | |
+| chair | Array of Chair | No | |
+| translator | Array of Translator | No | |
+| update-to | Array of Update | No | |
+| update-policy | URL | No | |
+
+## Work Nested Types
+
+### Funder
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| DOI | String | No | |
+| name | String | Yes | |
+| award | Array of String | No | |
+| doi-asserted-by | String | No | |
+
+### Contributor
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| given-name | String | No | |
+| family-name | String | Yes | |
+| ORCID | String | No | |
+| affiliation | Array of Affiliation | No | |
+
+### Affiliation
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| given-name | String | No | |
+| family-name | String | Yes | |
+| ORCID | String | No | |
+| affiliation | Array of Affiliation | No | |
+
+### Date
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| date-parts | Array of Number | Yes | |
+| timestamp | Number | No | |
+| date-time | String | No | |
+
+### Update
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| updated | Date | Yes | |
+| DOI | String | Yes | |
+| type | String | Yes | |
+| label | String | No | |
+
+### Assertion
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| label | String | No | |
+| name | String | Yes | |
+| order | Number | No | |
+| value | String | Yes | |
+| group | Assertion Group | No | |
+
+### Assertion Group
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| label | String | No | |
+| name | String | Yes | |
+
+### License
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| content-version | String | Yes | |
+| delay-in-days | Number | Yes | |
+| start | Date | Yes | |
+| URL | URL | Yes | |
+
+### Resource Link
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| intended-application | String | Yes | |
+| content-version | String | Yes | |
+| content-type | String | No | |
+| URL | URL | Yes | |

From 4866e7f702fa014b7ee552ebfde92651e8a8bf83 Mon Sep 17 00:00:00 2001
From: Karl Jonathan Ward 
Date: Mon, 11 Jul 2016 14:09:55 -0400
Subject: [PATCH 109/219] Single contributor type

---
 api_format.md | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/api_format.md b/api_format.md
index 756a24f..8ca41ff 100644
--- a/api_format.md
+++ b/api_format.md
@@ -36,10 +36,10 @@
 | license | Array of License | No | |
 | funder | Array of Funder | No | |
 | assertion | Array of Assertion | No | |
-| author | Array of Author | No | |
-| editor | Array of Editor | No | |
-| chair | Array of Chair | No | |
-| translator | Array of Translator | No | |
+| author | Array of Contributor | No | |
+| editor | Array of Contributor | No | |
+| chair | Array of Contributor | No | |
+| translator | Array of Contributor | No | |
 | update-to | Array of Update | No | |
 | update-policy | URL | No | |
 

From 5a0a3c1b257ce10637ff49eed40c5ff5fbd3e77a Mon Sep 17 00:00:00 2001
From: Karl Jonathan Ward 
Date: Mon, 11 Jul 2016 14:16:04 -0400
Subject: [PATCH 110/219] Internal links to sub-types

---
 api_format.md | 36 +++++++++++++++++-------------------
 1 file changed, 17 insertions(+), 19 deletions(-)

diff --git a/api_format.md b/api_format.md
index 8ca41ff..6a2c90f 100644
--- a/api_format.md
+++ b/api_format.md
@@ -23,25 +23,26 @@
 | DOI | String | Yes | |
 | member | String | Yes | |
 | type | String | Yes | Enumeration, one of the type ids from `https://api.crossref.org/v1/types` |
-| created | Date | Yes | |
-| deposited | Date | Yes | |
-| indexed | Date | Yes | |
-| published-print | Date | No | |
-| published-online | Date | No | |
+| created | [Date](#date) | Yes | |
+| deposited | [Date](#date) | Yes | |
+| indexed | [Date](#date) | Yes | |
+| published-print | [Date](#date) | No | |
+| published-online | [Date](#date) | No | |
 | issued | Date | Yes | Eariest of published-print and published-online |
 | subject | Array of String | No | |
 | ISSN | Array of String | No | |
 | ISBN | Array of String | No | |
 | archive | Array of String | No | |
-| license | Array of License | No | |
-| funder | Array of Funder | No | |
-| assertion | Array of Assertion | No | |
-| author | Array of Contributor | No | |
-| editor | Array of Contributor | No | |
-| chair | Array of Contributor | No | |
-| translator | Array of Contributor | No | |
-| update-to | Array of Update | No | |
+| license | Array of [License](#license) | No | |
+| funder | Array of [Funder](#funder) | No | |
+| assertion | Array of [Assertion](#assertion) | No | |
+| author | Array of [Contributor](#contributor) | No | |
+| editor | Array of [Contributor](#contributor) | No | |
+| chair | Array of [Contributor](#contributor) | No | |
+| translator | Array of [Contributor](#contributor) | No | |
+| update-to | Array of [Update](#update) | No | |
 | update-policy | URL | No | |
+| link | Array of [Resource Link](#resource-link) | No | URLs to full-text locations |
 
 ## Work Nested Types
 
@@ -61,16 +62,13 @@
 | given-name | String | No | |
 | family-name | String | Yes | |
 | ORCID | String | No | |
-| affiliation | Array of Affiliation | No | |
+| affiliation | Array of [Affiliation](#affiliation) | No | |
 
 ### Affiliation
 
 | Field | Type | Required | Description |
 |-------|------|----------|-------------|
-| given-name | String | No | |
-| family-name | String | Yes | |
-| ORCID | String | No | |
-| affiliation | Array of Affiliation | No | |
+| name | String | Yes | |
 
 ### Date
 
@@ -97,7 +95,7 @@
 | name | String | Yes | |
 | order | Number | No | |
 | value | String | Yes | |
-| group | Assertion Group | No | |
+| group | [Assertion Group](#assertion-group) | No | |
 
 ### Assertion Group
 

From e08b0ceb8b424e1addd19aac12e6fc4230d45e57 Mon Sep 17 00:00:00 2001
From: Karl Jonathan Ward 
Date: Mon, 11 Jul 2016 14:33:21 -0400
Subject: [PATCH 111/219] More field descriptions

---
 api_format.md | 22 +++++++++++-----------
 1 file changed, 11 insertions(+), 11 deletions(-)

diff --git a/api_format.md b/api_format.md
index 6a2c90f..829213f 100644
--- a/api_format.md
+++ b/api_format.md
@@ -13,23 +13,23 @@
 | publisher | String | Yes | Name of work's publisher |
 | title | Array of String | Yes | Work titles, including original language title and translated titles |
 | subtitle | Array of String | No | Work subtitles, including original language and translated |
-| container-title | Array of String | No |
+| container-title | Array of String | No | Titles (full and abbreviated) of the containing work (usually a book or journal.) |
 | reference-count | Number | Yes | Count of outbound references deposited with Crossref |
 | issue | String | No | Issue number of an article's journal |
 | volume | String | No | Volume number of an article's journal |
 | page | String | No | Pages numbers of an article within its journal |
 | source | String | Yes | Currently always `crossref` |
-| prefix | String | Yes | |
-| DOI | String | Yes | |
-| member | String | Yes | |
+| prefix | URL | Yes | DOI prefix identifier of the form `http://id.crossref.org/prefix/DOI_PREFIX` |
+| DOI | String | Yes | DOI of the work |
+| member | URL | Yes | Member identifier of the form `http://id.crossref.org/member/MEMBER_ID` |
 | type | String | Yes | Enumeration, one of the type ids from `https://api.crossref.org/v1/types` |
-| created | [Date](#date) | Yes | |
-| deposited | [Date](#date) | Yes | |
-| indexed | [Date](#date) | Yes | |
-| published-print | [Date](#date) | No | |
-| published-online | [Date](#date) | No | |
-| issued | Date | Yes | Eariest of published-print and published-online |
-| subject | Array of String | No | |
+| created | [Date](#date) | Yes | Date on which the DOI was first registered |
+| deposited | [Date](#date) | Yes | Date on which the work metadata was most recently updated |
+| indexed | [Date](#date) | Yes | Date on which the work metadata was most recently indexed. Re-indexing does not imply a metadata change, see `deposited` for the most recent metadata change date |
+| published-print | [Date](#date) | No | Date on which the work was published in print |
+| published-online | [Date](#date) | No | Date on which the work was published online |
+| issued | Date | Yes | Eariest of `published-print` and `published-online` |
+| subject | Array of String | No | Subject category names, a controlled vocabulary from Sci-Val. Available for most journal articles |
 | ISSN | Array of String | No | |
 | ISBN | Array of String | No | |
 | archive | Array of String | No | |

From b425f0705db6aeef5016955c78dd72a0eef896dd Mon Sep 17 00:00:00 2001
From: Karl Jonathan Ward 
Date: Mon, 11 Jul 2016 14:38:19 -0400
Subject: [PATCH 112/219] Order by required

---
 api_format.md | 26 +++++++++++++-------------
 1 file changed, 13 insertions(+), 13 deletions(-)

diff --git a/api_format.md b/api_format.md
index 829213f..de47793 100644
--- a/api_format.md
+++ b/api_format.md
@@ -12,12 +12,7 @@
 |-------|------|----------|-------------|
 | publisher | String | Yes | Name of work's publisher |
 | title | Array of String | Yes | Work titles, including original language title and translated titles |
-| subtitle | Array of String | No | Work subtitles, including original language and translated |
-| container-title | Array of String | No | Titles (full and abbreviated) of the containing work (usually a book or journal.) |
 | reference-count | Number | Yes | Count of outbound references deposited with Crossref |
-| issue | String | No | Issue number of an article's journal |
-| volume | String | No | Volume number of an article's journal |
-| page | String | No | Pages numbers of an article within its journal |
 | source | String | Yes | Currently always `crossref` |
 | prefix | URL | Yes | DOI prefix identifier of the form `http://id.crossref.org/prefix/DOI_PREFIX` |
 | DOI | String | Yes | DOI of the work |
@@ -26,9 +21,14 @@
 | created | [Date](#date) | Yes | Date on which the DOI was first registered |
 | deposited | [Date](#date) | Yes | Date on which the work metadata was most recently updated |
 | indexed | [Date](#date) | Yes | Date on which the work metadata was most recently indexed. Re-indexing does not imply a metadata change, see `deposited` for the most recent metadata change date |
+| issued | Date | Yes | Eariest of `published-print` and `published-online` |
+| subtitle | Array of String | No | Work subtitles, including original language and translated |
+| container-title | Array of String | No | Titles (full and abbreviated) of the containing work (usually a book or journal.) |
+| issue | String | No | Issue number of an article's journal |
+| volume | String | No | Volume number of an article's journal |
+| page | String | No | Pages numbers of an article within its journal |
 | published-print | [Date](#date) | No | Date on which the work was published in print |
 | published-online | [Date](#date) | No | Date on which the work was published online |
-| issued | Date | Yes | Eariest of `published-print` and `published-online` |
 | subject | Array of String | No | Subject category names, a controlled vocabulary from Sci-Val. Available for most journal articles |
 | ISSN | Array of String | No | |
 | ISBN | Array of String | No | |
@@ -41,7 +41,7 @@
 | chair | Array of [Contributor](#contributor) | No | |
 | translator | Array of [Contributor](#contributor) | No | |
 | update-to | Array of [Update](#update) | No | |
-| update-policy | URL | No | |
+| update-policy | URL | No | Link to an update policy covering Crossmark updates for this work |
 | link | Array of [Resource Link](#resource-link) | No | URLs to full-text locations |
 
 ## Work Nested Types
@@ -50,8 +50,8 @@
 
 | Field | Type | Required | Description |
 |-------|------|----------|-------------|
-| DOI | String | No | |
 | name | String | Yes | |
+| DOI | String | No | |
 | award | Array of String | No | |
 | doi-asserted-by | String | No | |
 
@@ -59,8 +59,8 @@
 
 | Field | Type | Required | Description |
 |-------|------|----------|-------------|
-| given-name | String | No | |
 | family-name | String | Yes | |
+| given-name | String | No | |
 | ORCID | String | No | |
 | affiliation | Array of [Affiliation](#affiliation) | No | |
 
@@ -91,18 +91,18 @@
 
 | Field | Type | Required | Description |
 |-------|------|----------|-------------|
-| label | String | No | |
 | name | String | Yes | |
-| order | Number | No | |
 | value | String | Yes | |
+| label | String | No | |
+| order | Number | No | |
 | group | [Assertion Group](#assertion-group) | No | |
 
 ### Assertion Group
 
 | Field | Type | Required | Description |
 |-------|------|----------|-------------|
-| label | String | No | |
 | name | String | Yes | |
+| label | String | No | |
 
 ### License
 
@@ -119,5 +119,5 @@
 |-------|------|----------|-------------|
 | intended-application | String | Yes | |
 | content-version | String | Yes | |
-| content-type | String | No | |
 | URL | URL | Yes | |
+| content-type | String | No | |

From 282c3bbbdb6ed4918c82e40e12bf7234ccf40ae4 Mon Sep 17 00:00:00 2001
From: Karl Jonathan Ward 
Date: Mon, 11 Jul 2016 14:58:55 -0400
Subject: [PATCH 113/219] More field descriptions

---
 api_format.md | 40 ++++++++++++++++++++--------------------
 1 file changed, 20 insertions(+), 20 deletions(-)

diff --git a/api_format.md b/api_format.md
index de47793..d997876 100644
--- a/api_format.md
+++ b/api_format.md
@@ -50,10 +50,10 @@
 
 | Field | Type | Required | Description |
 |-------|------|----------|-------------|
-| name | String | Yes | |
-| DOI | String | No | |
-| award | Array of String | No | |
-| doi-asserted-by | String | No | |
+| name | String | Yes | Funding body primary name |
+| DOI | String | No | Optional [Open Funder Registry](http://www.crossref.org/fundingdata/registry.html) DOI uniquely identifing the funding body |
+| award | Array of String | No | Award number(s) for awards given by the funding body |
+| doi-asserted-by | String | No | Either `crossref` or `publisher` |
 
 ### Contributor
 
@@ -61,7 +61,7 @@
 |-------|------|----------|-------------|
 | family-name | String | Yes | |
 | given-name | String | No | |
-| ORCID | String | No | |
+| ORCID | URL | No | URL-form of an [ORCID](http://orcid.org) identifier |
 | affiliation | Array of [Affiliation](#affiliation) | No | |
 
 ### Affiliation
@@ -74,18 +74,18 @@
 
 | Field | Type | Required | Description |
 |-------|------|----------|-------------|
-| date-parts | Array of Number | Yes | |
-| timestamp | Number | No | |
-| date-time | String | No | |
+| date-parts | Array of Number | Yes | Ordered array of `year`, `month`, `day of month`. Only `year` is required |
+| timestamp | Number | No | Seconds since UNIX epoch |
+| date-time | String | No | ISO 8601 date time |
 
 ### Update
 
 | Field | Type | Required | Description |
 |-------|------|----------|-------------|
-| updated | Date | Yes | |
-| DOI | String | Yes | |
-| type | String | Yes | |
-| label | String | No | |
+| updated | Date | Yes | Date on which the update was published |
+| DOI | String | Yes | DOI of the updated work |
+| type | String | Yes | The type of update, for example `retraction` or `correction` |
+| label | String | No | A display-friendly label for the update type |
 
 ### Assertion
 
@@ -108,16 +108,16 @@
 
 | Field | Type | Required | Description |
 |-------|------|----------|-------------|
-| content-version | String | Yes | |
-| delay-in-days | Number | Yes | |
-| start | Date | Yes | |
-| URL | URL | Yes | |
+| content-version | String | Yes | Either `vor` (version of record,) `am` (accepted manuscript,) `tdm` (text and data mining) or `unspecified` |
+| delay-in-days | Number | Yes | Number of days between the publication date of the work and the start date of this license |
+| start | Date | Yes | Date on which this license begins to take effect |
+| URL | URL | Yes | Link to a web page describing this license |
 
 ### Resource Link
 
 | Field | Type | Required | Description |
 |-------|------|----------|-------------|
-| intended-application | String | Yes | |
-| content-version | String | Yes | |
-| URL | URL | Yes | |
-| content-type | String | No | |
+| intended-application | String | Yes | Either `text-mining` or `unspecified` |
+| content-version | String | Yes | Either `vor` (version of record,) `am` (accepted manuscript) or `unspecified` |
+| URL | URL | Yes | Direct link to a full-text download location |
+| content-type | String | No | Content type (or MIME type) of the full-text object |

From 63056a8d4ea277dd8eb6666dc31a45283a0edef2 Mon Sep 17 00:00:00 2001
From: Karl Jonathan Ward 
Date: Mon, 11 Jul 2016 15:04:06 -0400
Subject: [PATCH 114/219] Add alternative-id

---
 api_format.md | 1 +
 1 file changed, 1 insertion(+)

diff --git a/api_format.md b/api_format.md
index d997876..3806045 100644
--- a/api_format.md
+++ b/api_format.md
@@ -43,6 +43,7 @@
 | update-to | Array of [Update](#update) | No | |
 | update-policy | URL | No | Link to an update policy covering Crossmark updates for this work |
 | link | Array of [Resource Link](#resource-link) | No | URLs to full-text locations |
+| alternative-id | String | No | Other identifiers for the work provided by the depositing member |
 
 ## Work Nested Types
 

From 28e55dfb3deb2b8089225b40c75072bee702c221 Mon Sep 17 00:00:00 2001
From: Karl Jonathan Ward 
Date: Mon, 11 Jul 2016 15:12:26 -0400
Subject: [PATCH 115/219] Mention clinical trial numbers

---
 api_format.md | 14 +++++++++++++-
 1 file changed, 13 insertions(+), 1 deletion(-)

diff --git a/api_format.md b/api_format.md
index 3806045..d6bfebb 100644
--- a/api_format.md
+++ b/api_format.md
@@ -13,7 +13,7 @@
 | publisher | String | Yes | Name of work's publisher |
 | title | Array of String | Yes | Work titles, including original language title and translated titles |
 | reference-count | Number | Yes | Count of outbound references deposited with Crossref |
-| source | String | Yes | Currently always `crossref` |
+| source | String | Yes | Currently always `CrossRef` |
 | prefix | URL | Yes | DOI prefix identifier of the form `http://id.crossref.org/prefix/DOI_PREFIX` |
 | DOI | String | Yes | DOI of the work |
 | member | URL | Yes | Member identifier of the form `http://id.crossref.org/member/MEMBER_ID` |
@@ -27,6 +27,7 @@
 | issue | String | No | Issue number of an article's journal |
 | volume | String | No | Volume number of an article's journal |
 | page | String | No | Pages numbers of an article within its journal |
+| article-number | String | No | |
 | published-print | [Date](#date) | No | Date on which the work was published in print |
 | published-online | [Date](#date) | No | Date on which the work was published online |
 | subject | Array of String | No | Subject category names, a controlled vocabulary from Sci-Val. Available for most journal articles |
@@ -43,6 +44,7 @@
 | update-to | Array of [Update](#update) | No | |
 | update-policy | URL | No | Link to an update policy covering Crossmark updates for this work |
 | link | Array of [Resource Link](#resource-link) | No | URLs to full-text locations |
+| clinical-trial-number | Array of [Clinical Trial Number](#clinical-trial-number) | No | |
 | alternative-id | String | No | Other identifiers for the work provided by the depositing member |
 
 ## Work Nested Types
@@ -56,6 +58,14 @@
 | award | Array of String | No | Award number(s) for awards given by the funding body |
 | doi-asserted-by | String | No | Either `crossref` or `publisher` |
 
+### Clinical Trial Number
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| clinical-trial-number | String | Yes | |
+| registry | String | Yes | |
+| type | String | No | |
+
 ### Contributor
 
 | Field | Type | Required | Description |
@@ -94,6 +104,8 @@
 |-------|------|----------|-------------|
 | name | String | Yes | |
 | value | String | Yes | |
+| URL | URL | No | |
+| explanation | URL | No | |
 | label | String | No | |
 | order | Number | No | |
 | group | [Assertion Group](#assertion-group) | No | |

From 41d6275ae9dd30d0683ed4b05884151ad25de3c9 Mon Sep 17 00:00:00 2001
From: Karl Jonathan Ward 
Date: Mon, 11 Jul 2016 15:39:26 -0400
Subject: [PATCH 116/219] Clinical trial field descriptions

---
 api_format.md | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/api_format.md b/api_format.md
index d6bfebb..18ce7a1 100644
--- a/api_format.md
+++ b/api_format.md
@@ -62,9 +62,9 @@
 
 | Field | Type | Required | Description |
 |-------|------|----------|-------------|
-| clinical-trial-number | String | Yes | |
-| registry | String | Yes | |
-| type | String | No | |
+| clinical-trial-number | String | Yes | Identifier of the clinical trial |
+| registry | String | Yes | DOI of the clinical trial regsitry that assigned the trial number |
+| type | String | No | One of `preResults`, `results` or `postResults` |
 
 ### Contributor
 

From d999b7b6609ff9972b884e343fcc04e669352abc Mon Sep 17 00:00:00 2001
From: Karl Jonathan Ward 
Date: Mon, 11 Jul 2016 16:13:02 -0400
Subject: [PATCH 117/219] Mention array nesting in dates

---
 api_format.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/api_format.md b/api_format.md
index 18ce7a1..8c50977 100644
--- a/api_format.md
+++ b/api_format.md
@@ -85,7 +85,7 @@
 
 | Field | Type | Required | Description |
 |-------|------|----------|-------------|
-| date-parts | Array of Number | Yes | Ordered array of `year`, `month`, `day of month`. Only `year` is required |
+| date-parts | Array of Number | Yes | Contains an ordered array of `year`, `month`, `day of month`. Only `year` is required. Note that the field contains a nested array, e.g. `[ [ 2006, 5, 19 ] ]` to conform to citeproc JSON dates |
 | timestamp | Number | No | Seconds since UNIX epoch |
 | date-time | String | No | ISO 8601 date time |
 

From d9f2a7594523cc3abbd480a53c9fe0edea04941e Mon Sep 17 00:00:00 2001
From: Karl Jonathan Ward 
Date: Mon, 11 Jul 2016 16:17:28 -0400
Subject: [PATCH 118/219] Link to api format document

---
 rest_api.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/rest_api.md b/rest_api.md
index badddf5..2d6a389 100644
--- a/rest_api.md
+++ b/rest_api.md
@@ -51,7 +51,7 @@ CrossRef asserts no claims of ownership to individual items of bibliographic met
 
 ## Overview
 
-The API is generally RESTFUL and returns results in JSON.
+The API is generally RESTFUL and returns results in JSON. JSON formats returned by the API are documented [here](https://github.com/CrossRef/rest-api-doc/blob/master/api_format.md).
 
 The API will only work for CrossRef DOIs. You can test the registration agency for a DOI using the following route:
 

From b8c3ad955d2b51aa09453f7afa280445a16c6c5b Mon Sep 17 00:00:00 2001
From: Karl Jonathan Ward 
Date: Wed, 13 Jul 2016 11:33:19 -0400
Subject: [PATCH 119/219] Separate out partial and full dates

---
 api_format.md | 20 +++++++++++++-------
 1 file changed, 13 insertions(+), 7 deletions(-)

diff --git a/api_format.md b/api_format.md
index 8c50977..a40c5b3 100644
--- a/api_format.md
+++ b/api_format.md
@@ -21,15 +21,15 @@
 | created | [Date](#date) | Yes | Date on which the DOI was first registered |
 | deposited | [Date](#date) | Yes | Date on which the work metadata was most recently updated |
 | indexed | [Date](#date) | Yes | Date on which the work metadata was most recently indexed. Re-indexing does not imply a metadata change, see `deposited` for the most recent metadata change date |
-| issued | Date | Yes | Eariest of `published-print` and `published-online` |
+| issued | [Partial Date](#partial-date) | Yes | Eariest of `published-print` and `published-online` |
 | subtitle | Array of String | No | Work subtitles, including original language and translated |
 | container-title | Array of String | No | Titles (full and abbreviated) of the containing work (usually a book or journal.) |
 | issue | String | No | Issue number of an article's journal |
 | volume | String | No | Volume number of an article's journal |
 | page | String | No | Pages numbers of an article within its journal |
 | article-number | String | No | |
-| published-print | [Date](#date) | No | Date on which the work was published in print |
-| published-online | [Date](#date) | No | Date on which the work was published online |
+| published-print | [Partial Date](#partial-date) | No | Date on which the work was published in print |
+| published-online | [Partial Date](#partial-date) | No | Date on which the work was published online |
 | subject | Array of String | No | Subject category names, a controlled vocabulary from Sci-Val. Available for most journal articles |
 | ISSN | Array of String | No | |
 | ISBN | Array of String | No | |
@@ -83,17 +83,23 @@
 
 ### Date
 
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| date-parts | Array of Number | Yes | Contains an ordered array of `year`, `month`, `day of month`. Note that the field contains a nested array, e.g. `[ [ 2006, 5, 19 ] ]` to conform to citeproc JSON dates |
+| timestamp | Number | Yes | Seconds since UNIX epoch |
+| date-time | String | Yes | ISO 8601 date time |
+
+### Partial Date
+
 | Field | Type | Required | Description |
 |-------|------|----------|-------------|
 | date-parts | Array of Number | Yes | Contains an ordered array of `year`, `month`, `day of month`. Only `year` is required. Note that the field contains a nested array, e.g. `[ [ 2006, 5, 19 ] ]` to conform to citeproc JSON dates |
-| timestamp | Number | No | Seconds since UNIX epoch |
-| date-time | String | No | ISO 8601 date time |
 
 ### Update
 
 | Field | Type | Required | Description |
 |-------|------|----------|-------------|
-| updated | Date | Yes | Date on which the update was published |
+| updated | [Partial Date](#partial-date) | Yes | Date on which the update was published |
 | DOI | String | Yes | DOI of the updated work |
 | type | String | Yes | The type of update, for example `retraction` or `correction` |
 | label | String | No | A display-friendly label for the update type |
@@ -123,7 +129,7 @@
 |-------|------|----------|-------------|
 | content-version | String | Yes | Either `vor` (version of record,) `am` (accepted manuscript,) `tdm` (text and data mining) or `unspecified` |
 | delay-in-days | Number | Yes | Number of days between the publication date of the work and the start date of this license |
-| start | Date | Yes | Date on which this license begins to take effect |
+| start | [Partial Date](#partial-date) | Yes | Date on which this license begins to take effect |
 | URL | URL | Yes | Link to a web page describing this license |
 
 ### Resource Link

From ba3b92dbe99c739f54606213cf8b38855cdf764d Mon Sep 17 00:00:00 2001
From: Geoffrey Bilder 
Date: Mon, 26 Sep 2016 14:46:58 +0100
Subject: [PATCH 120/219] make issue tracker more prominent

---
 rest_api.md | 8 +++-----
 1 file changed, 3 insertions(+), 5 deletions(-)

diff --git a/rest_api.md b/rest_api.md
index 2d6a389..bb504e1 100644
--- a/rest_api.md
+++ b/rest_api.md
@@ -32,18 +32,16 @@
 - v27, 2015-10-30, Added `cursor` parameter to `/works` resources
 - v28, 2016-05-09, Added link to source of category lables
 - v29, 2016-05-24, Added field queries
+- v30, 2016-09-26, Highlight issue tracker
 
 ## 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.
 
-## Reporting issues
+## Reporting issues, requesting features
 
-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).
+Please report problems with the API or the documentation 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
 

From 4f30906ded32e2e2ab2e614ead9c196243c1ff8c Mon Sep 17 00:00:00 2001
From: Geoffrey Bilder 
Date: Wed, 5 Oct 2016 08:53:35 +0200
Subject: [PATCH 121/219] document `has-clinical-trial-number` + `has-abstract`
 filters

---
 rest_api.md | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/rest_api.md b/rest_api.md
index bb504e1..2b91e40 100644
--- a/rest_api.md
+++ b/rest_api.md
@@ -33,6 +33,7 @@
 - v28, 2016-05-09, Added link to source of category lables
 - v29, 2016-05-24, Added field queries
 - v30, 2016-09-26, Highlight issue tracker
+- v31, 2016-10-05, document `has-clinical-trial-number` and `has-abstract` filters
 
 ## Background
 
@@ -301,6 +302,8 @@ Filters allow you to narrow queries. All filter results are lists.  The followin
 | `has-affiliation` | | metadata for records that have any affiliation information |
 | `alternative-id` | | metadata for records with the given alternative ID, which may be a publisher-specific ID, or any other identifier a publisher may have provided |
 | `article-number` | | metadata for records with a given article number |
+| `has-abstract` | | metadata for records which include an abstract |
+| `has-clinical-trial-number` | | metadata for records which include a clinical trial number |
 
 ### Multiple filters
 

From 1b494716308fcc36e8880cdbe3011e6c2e9b2eef Mon Sep 17 00:00:00 2001
From: Geoffrey Bilder 
Date: Thu, 27 Oct 2016 16:56:15 +0100
Subject: [PATCH 122/219] document rate limit headers

---
 rest_api.md | 5 +++++
 1 file changed, 5 insertions(+)

diff --git a/rest_api.md b/rest_api.md
index 2b91e40..6a7c187 100644
--- a/rest_api.md
+++ b/rest_api.md
@@ -34,6 +34,7 @@
 - v29, 2016-05-24, Added field queries
 - v30, 2016-09-26, Highlight issue tracker
 - v31, 2016-10-05, document `has-clinical-trial-number` and `has-abstract` filters
+- v32, 2016-10-27, document rate limit headers
 
 ## Background
 
@@ -48,6 +49,10 @@ Please report problems with the API or the documentation on our [issue tracker](
 
 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/).
 
+## Rate limits
+
+From time to time Crossref needs to empose rate limits to ensure that the free API is usable by all. Any rate limits that are in effect will be advertised in the `X-Rate-Limit-Limit` and `X-Rate-Limit-Interval` HTTP headers.
+
 ## Overview
 
 The API is generally RESTFUL and returns results in JSON. JSON formats returned by the API are documented [here](https://github.com/CrossRef/rest-api-doc/blob/master/api_format.md).

From 761d26d87e1b13b167b4c8404c56f943c29db3c2 Mon Sep 17 00:00:00 2001
From: Geoffrey Bilder 
Date: Thu, 27 Oct 2016 17:22:13 +0100
Subject: [PATCH 123/219] correct spelling

---
 rest_api.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/rest_api.md b/rest_api.md
index 6a7c187..ddf9e27 100644
--- a/rest_api.md
+++ b/rest_api.md
@@ -51,7 +51,7 @@ CrossRef asserts no claims of ownership to individual items of bibliographic met
 
 ## Rate limits
 
-From time to time Crossref needs to empose rate limits to ensure that the free API is usable by all. Any rate limits that are in effect will be advertised in the `X-Rate-Limit-Limit` and `X-Rate-Limit-Interval` HTTP headers.
+From time to time Crossref needs to impose rate limits to ensure that the free API is usable by all. Any rate limits that are in effect will be advertised in the `X-Rate-Limit-Limit` and `X-Rate-Limit-Interval` HTTP headers.
 
 ## Overview
 

From 40ffccbd6e993fa22420e0de5418fbe6e034ce4f Mon Sep 17 00:00:00 2001
From: Geoffrey Bilder 
Date: Thu, 27 Oct 2016 17:25:08 +0100
Subject: [PATCH 124/219] *cough* de-camel-case "Crossref"

---
 rest_api.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/rest_api.md b/rest_api.md
index ddf9e27..d643e87 100644
--- a/rest_api.md
+++ b/rest_api.md
@@ -1,4 +1,4 @@
-# CrossRef REST API
+# Crossref REST API
 
 ## Version History
 

From d8030c794669ffb6d9f1fce3eb3ff824cc2afc9c Mon Sep 17 00:00:00 2001
From: Geoffrey Bilder 
Date: Mon, 7 Nov 2016 16:09:41 +0000
Subject: [PATCH 125/219] guidance of offset vs cursor

---
 rest_api.md | 8 ++++++--
 1 file changed, 6 insertions(+), 2 deletions(-)

diff --git a/rest_api.md b/rest_api.md
index d643e87..71d840f 100644
--- a/rest_api.md
+++ b/rest_api.md
@@ -35,6 +35,7 @@
 - v30, 2016-09-26, Highlight issue tracker
 - v31, 2016-10-05, document `has-clinical-trial-number` and `has-abstract` filters
 - v32, 2016-10-27, document rate limit headers
+- v33, 2016-11-07, guidance on when to use `offset` vs `cursor`
 
 ## Background
 
@@ -182,11 +183,12 @@ Parameters can be used to query, filter and control the results returned by the
 | `query`                      | limited [DisMax](https://wiki.apache.org/solr/DisMax) query terms |
 | `filter={filter_name}:{value}`| filter results by specific fields |
 | `rows={#}`                   | results per per page | 
-| `offset={#}`                 | result offset |                         
+| `offset={#}` (mak 10k)               | result offset (user `cursor` for larger `/works` result sets)  |                         
 | `sample={#}`                 | return random N results |
 | `sort={#}`                   | sort results by a certain field |
 | `order={#}`                  | set the sort order to `asc` or `desc` |
 | `facet=t`                    | enable facet information in responses |
+| `cursor={#}`		       | deep page through `/works` result sets |
 
 Multiple filters can be specified by separating name:value pairs with a comma:
 
@@ -351,7 +353,7 @@ every time there is a change to metadata requiring a reindex.
 
 ## Result controls
 
-You can control the delivery and selection  results using the `rows`, `offset` and `sample` parameters. 
+You can control the delivery and selection results using the `rows`, `offset` and `sample` parameters. If you are expecting results beyond 10K, then use a `cursor` to deep page through the results. 
 
 ### Rows 
 
@@ -371,6 +373,8 @@ The number of returned items is controlled by the `rows` parameter, but you can
 
     http://api.crossref.org/works?query=allen+renear&rows=5&offset=5
 
+Offsets for `/works` are limited to 10K. Use `cursor` (see below) for larger `/works` results sets.
+
 ### Deep Paging with Cursors
 
 Using large `offset` values can result in extremely long response times. Offsets in the 100,000s and beyond will likely cause a timeout before the API is able to respond. An alternative to paging through very large result sets (like a corpus used for text and data mining) it to use the API's exposure of Solr's deep paging cursors. Any combination of query, filters and facets may be used with deep paging cursors. While `rows` may be specified along with `cursor`, `offset` and `sample` cannot be used. To use deep paging make a query as normal, but include the `cursor` parameter with a value of `*`. In this example we will page through all `journal-article` works from member `311`:

From 04f821074af63307591790f08a8c25552904288f Mon Sep 17 00:00:00 2001
From: Christian Pietsch 
Date: Mon, 14 Nov 2016 09:43:13 +0100
Subject: [PATCH 126/219] fix copy and paste error

---
 rest_api_koans.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/rest_api_koans.md b/rest_api_koans.md
index 90cb25b..bc07b19 100644
--- a/rest_api_koans.md
+++ b/rest_api_koans.md
@@ -27,7 +27,7 @@ You might start by wondering how much and what kinds of data exist in the CrossR
 
 ### How many report DOIs does CrossRef have?
 
-    http://api.crossref.org/types/journal-article/works?rows=0
+    http://api.crossref.org/types/report/works?rows=0
 
 But eventually you will probably want to start looking at metadata records
 

From 9e030166abb7b9fdb6fa947fa29f98147a667303 Mon Sep 17 00:00:00 2001
From: Karl Jonathan Ward 
Date: Fri, 20 Jan 2017 16:05:12 +0000
Subject: [PATCH 127/219] CrossRef -> Crossref

---
 rest_api.md | 12 ++++++------
 1 file changed, 6 insertions(+), 6 deletions(-)

diff --git a/rest_api.md b/rest_api.md
index 71d840f..e195153 100644
--- a/rest_api.md
+++ b/rest_api.md
@@ -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
@@ -39,7 +39,7 @@
 
 ## 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) for funding agencies](https://github.com/CrossRef/rest-api-doc/blob/master/funder_kpi_metadata_best_practice.md), for background.
 
 ## Reporting issues, requesting features
 
@@ -48,7 +48,7 @@ Please report problems with the API or the documentation on our [issue tracker](
 
 ## 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/).
 
 ## Rate limits
 
@@ -58,11 +58,11 @@ From time to time Crossref needs to impose rate limits to ensure that the free A
 
 The API is generally RESTFUL and returns results in JSON. JSON formats returned by the API are documented [here](https://github.com/CrossRef/rest-api-doc/blob/master/api_format.md).
 
-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`
 
@@ -85,7 +85,7 @@ Will return the following result:
       }
     }
 
-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
 

From 69116e9e2ea25aa178934096c0e340c52f5c6fb0 Mon Sep 17 00:00:00 2001
From: kmeddings 
Date: Mon, 20 Mar 2017 14:31:11 +0000
Subject: [PATCH 128/219] Update rest_api.md

---
 rest_api.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/rest_api.md b/rest_api.md
index e195153..4aa47b1 100644
--- a/rest_api.md
+++ b/rest_api.md
@@ -48,7 +48,7 @@ Please report problems with the API or the documentation on our [issue tracker](
 
 ## 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](https://www.crossref.org/privacy/).
 
 ## Rate limits
 

From e72e3fe8e0a43fd0af13295dfa98cb25fe196d5d Mon Sep 17 00:00:00 2001
From: Alex 
Date: Wed, 5 Apr 2017 20:35:26 +0100
Subject: [PATCH 129/219] fixed typo

licnese to license
---
 rest_api_koans.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/rest_api_koans.md b/rest_api_koans.md
index 90cb25b..4d95e22 100644
--- a/rest_api_koans.md
+++ b/rest_api_koans.md
@@ -59,7 +59,7 @@ So let's look at specific records
 
     TBD
 
-Interesting. There is licnese information in there and full text links.
+Interesting. There is license information in there and full text links.
 
 ## How many works have license information?
 

From 9bebf1255a8cda1ef135ae55f2e7a46bfd4103d3 Mon Sep 17 00:00:00 2001
From: Alex 
Date: Wed, 5 Apr 2017 20:39:20 +0100
Subject: [PATCH 130/219] fixed typo "reasearcher"

---
 rest_api_koans.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/rest_api_koans.md b/rest_api_koans.md
index 4d95e22..84e5d82 100644
--- a/rest_api_koans.md
+++ b/rest_api_koans.md
@@ -177,7 +177,7 @@ though once you have a member ID ('98', in this case), you should use that inste
 
     http://api.crossref.org/licenses?filter=issn:2090-8091
 
-## What licenses does a reasearcher with a particular ORCID publish under
+## What licenses does a researcher with a particular ORCID publish under
 
     http://api.crossref.org/licenses?filter=orcid:0000-0003-1340-5202
 

From c6642982a132c38bcb3ab64a22380d350b7998a3 Mon Sep 17 00:00:00 2001
From: Geoffrey Bilder 
Date: Wed, 26 Apr 2017 08:20:09 +0100
Subject: [PATCH 131/219] add info about HTTPS supprt

---
 rest_api.md | 49 +++++++++++++++++++++++++------------------------
 1 file changed, 25 insertions(+), 24 deletions(-)

diff --git a/rest_api.md b/rest_api.md
index 4aa47b1..0a4c635 100644
--- a/rest_api.md
+++ b/rest_api.md
@@ -36,6 +36,7 @@
 - v31, 2016-10-05, document `has-clinical-trial-number` and `has-abstract` filters
 - v32, 2016-10-27, document rate limit headers
 - v33, 2016-11-07, guidance on when to use `offset` vs `cursor`
+- v34, 2017-04-26, document support for HTTPS. Update examples to use HTTPS.
 
 ## Background
 
@@ -60,7 +61,7 @@ The API is generally RESTFUL and returns results in JSON. JSON formats returned
 
 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`
+`https://api.crossref.org/works/{doi}/agency`
 
 Testing the following Crossref DOI:
 
@@ -68,7 +69,7 @@ Testing the following Crossref DOI:
 
 Using the URL:
 
-`http://api.crossref.org/works/10.1037/0003-066X.59.1.29/agency`
+`https://api.crossref.org/works/10.1037/0003-066X.59.1.29/agency`
 
 Will return the following result:
 
@@ -142,7 +143,7 @@ These can be used alone like this
 | resource      | description                       |
 |:--------------|:----------------------------------|
 | `/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)
+| `/funders`    | returns a list of all funders in the [FundRef Registry](https://www.crossref.org/fundref/fundref_registry.html)
 | `/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 |
@@ -192,11 +193,11 @@ Parameters can be used to query, filter and control the results returned by the
 
 Multiple filters can be specified by separating name:value pairs with a comma:
 
-    http://api.crossref.org/works?filter=has-orcid:true,from-pub-date:2004-04-04
+    https://api.crossref.org/works?filter=has-orcid:true,from-pub-date:2004-04-04
 
 ### Example query using URI parameters
 
-    http://api.crossref.org/funders/100000015/works?query=global+state&filter=has-orcid:true&rows=1
+    https://api.crossref.org/funders/100000015/works?query=global+state&filter=has-orcid:true&rows=1
 
 ## Queries
 
@@ -205,7 +206,7 @@ can refine queries as follows.
 
 Works that include "renear" but not "ontologies":
 
-    http://api.crossref.org/works?query=renear+-ontologies
+    https://api.crossref.org/works?query=renear+-ontologies
 	
 ## Field Queries
 
@@ -213,12 +214,12 @@ Field queries are available on some routes and allow for queries that match only
 of metadata. For example, this query matches records that contain the tokens `richard` or `feynman` (or both)
 in any author field:
 
-    http://api.crossref.org/works?query.author=richard+feynman
+    https://api.crossref.org/works?query.author=richard+feynman
 	
 Field queries can be combined with the general `query` paramter and each other. Each query parameter
 is ANDed with the others:
 
-    http://api.crossref.org/works?query.title=room+at+the+bottom&query.author=richard+feynman
+    https://api.crossref.org/works?query.title=room+at+the+bottom&query.author=richard+feynman
 	
 ### `/works` Field Queries
 
@@ -250,7 +251,7 @@ sorted. Possible values are:
 
 An example that sorts results in order of publication, beginning with the least recent:
 
-    http://api.crossref.org/works?query=josiah+carberry&sort=published&order=asc
+    https://api.crossref.org/works?query=josiah+carberry&sort=published&order=asc
 
 ## Facet Counts
 
@@ -359,11 +360,11 @@ You can control the delivery and selection results using the `rows`, `offset` an
 
 Normally, results are returned 20 at a time. You can control the number of results returns by using the `rows` parameter. To limit results to 5, for example, you could do the following:
 
-    http://api.crossref.org/works?query=allen+renear&rows=5
+    https://api.crossref.org/works?query=allen+renear&rows=5
 
 If you would just like to get the `summary` of the results, you can set the rows to 0 (zero).
 
-    http://api.crossref.org/works?query=allen+renear&rows=0
+    https://api.crossref.org/works?query=allen+renear&rows=0
     
 The maximum number rows you can ask for in one query is `1000`.
 
@@ -371,7 +372,7 @@ The maximum number rows you can ask for in one query is `1000`.
 
 The number of returned items is controlled by the `rows` parameter, but you can select the offset into the result list by using the `offset` parameter.  So, for example, to select the second set of 5 results (i.e. results 6 through 10), you would do the following:
 
-    http://api.crossref.org/works?query=allen+renear&rows=5&offset=5
+    https://api.crossref.org/works?query=allen+renear&rows=5&offset=5
 
 Offsets for `/works` are limited to 10K. Use `cursor` (see below) for larger `/works` results sets.
 
@@ -379,11 +380,11 @@ Offsets for `/works` are limited to 10K. Use `cursor` (see below) for larger `/w
 
 Using large `offset` values can result in extremely long response times. Offsets in the 100,000s and beyond will likely cause a timeout before the API is able to respond. An alternative to paging through very large result sets (like a corpus used for text and data mining) it to use the API's exposure of Solr's deep paging cursors. Any combination of query, filters and facets may be used with deep paging cursors. While `rows` may be specified along with `cursor`, `offset` and `sample` cannot be used. To use deep paging make a query as normal, but include the `cursor` parameter with a value of `*`. In this example we will page through all `journal-article` works from member `311`:
 
-    http://api.crossref.org/members/311/works?filter=type:journal-article&cursor=*
+    https://api.crossref.org/members/311/works?filter=type:journal-article&cursor=*
 
 A `next-cursor` field will be provided in the JSON response. To get the next page of results, pass the value of `next-cursor` as the `cursor` parameter:
 
-    http://api.crossref.org/members/311/works?filter=type:journal-article&cursor=AoE/CGh0dHA6Ly9keC5kb2kub3JnLzEwLjEwMDIvdGRtX2xpY2Vuc2VfMQ==
+    https://api.crossref.org/members/311/works?filter=type:journal-article&cursor=AoE/CGh0dHA6Ly9keC5kb2kub3JnLzEwLjEwMDIvdGRtX2xpY2Vuc2VfMQ==
  
 Clients should check the number of returned items. If the number of returned items is fewer than the number of expected rows then the end of the result set has been reached. Using `next-cursor` beyond this point will result in responses with an empty items list.
 
@@ -393,7 +394,7 @@ The `cursor` parameter is available on all `/works` resources.
 
 Being able to select random results is useful for both testing and sampling. You can use the `sample` parameter to retrieve random results. So, for example, the following select 10 random works:
 
-    http://api.crossref.org/works?sample=10
+    https://api.crossref.org/works?sample=10
     
 Note that when you use the `sample` parameter, the `rows` and `offset` parameters are ignored.
 
@@ -402,41 +403,41 @@ Note that when you use the `sample` parameter, the `rows` and `offset` parameter
 
 **All works published by owner prefix `10.1016` in January 2010**
 
-    http://api.crossref.org/prefixes/10.1016/works?filter=from-pub-date:2010-01,until-pub-date:2010-01
+    https://api.crossref.org/prefixes/10.1016/works?filter=from-pub-date:2010-01,until-pub-date:2010-01
 
 **All works funded by `10.13039/100000001` that have a CC-BY license**
 
-    http://api.crossref.org/funders/10.13039/100000001/works?filter=license.url:http://creativecommons.org/licenses/by/3.0/deed.en_US
+    https://api.crossref.org/funders/10.13039/100000001/works?filter=license.url:https://creativecommons.org/licenses/by/3.0/deed.en_US
 
 **All works published by owner prefix 10.5555 from February 2010 to February 2013 that have a CC-BY license**
 
-    http://api.crossref.org/prefixes/10.5555/works?filter=license.url:http://creativecommons.org/licenses/by/3.0/deed.en_US,from-pub-date:2010-02,until-pub-date:2013-02
+    https://api.crossref.org/prefixes/10.5555/works?filter=license.url:https://creativecommons.org/licenses/by/3.0/deed.en_US,from-pub-date:2010-02,until-pub-date:2013-02
 
 **All works funded by `10.13039/100000015` where license = CC-BY and embargo <= 365 days**
 
-    http://api.crossref.org/funders/10.13039/100000015/works?filter=license.url:http://creativecommons.org/licenses/by/3.0/deed.en_US,license.delay:365
+    https://api.crossref.org/funders/10.13039/100000015/works?filter=license.url:https://creativecommons.org/licenses/by/3.0/deed.en_US,license.delay:365
 
 Note that the filters for license URL and maximum license embargo period (license.url and license.delay) combine to filter each document's metadata for a license with both of these properties.
 
 **All works where the archive partner listed = 'CLOCKSS'**
 
-    http://api.crossref.org/works?filter=archive:CLOCKSS
+    https://api.crossref.org/works?filter=archive:CLOCKSS
     
 **All members with `hind` in their name (e.g. Hindawi)**
 
-    http://api.crossref.org/members?query=hind
+    https://api.crossref.org/members?query=hind
     
 **All licenses linked to works published by Elsevier**
 
-    http://api.crossref.org/licenses?filter=member:78
+    https://api.crossref.org/licenses?filter=member:78
     
 **All licenses applied to works published in the journal `Pathology Research International`**
 
-    http://api.crossref.org/licenses?filter=issn:2090-8091
+    https://api.crossref.org/licenses?filter=issn:2090-8091
     
 **All works with an award numbered roughly `1 F31 MH11745` also awarded by funder with ID `10.13039/100000025`:
 
-    http://api.crossref.org/works?filter=award.number:1F31MH11745,award.funder:10.13039/100000025
+    https://api.crossref.org/works?filter=award.number:1F31MH11745,award.funder:10.13039/100000025
 
 ## Versioning
 

From 1f5eb6b0d95ee88b888d07a732e2494861a3d0e1 Mon Sep 17 00:00:00 2001
From: Geoffrey Bilder 
Date: Wed, 26 Apr 2017 08:21:42 +0100
Subject: [PATCH 132/219] add info about examples using HTTPS

---
 rest_api.md | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/rest_api.md b/rest_api.md
index 0a4c635..7a4035f 100644
--- a/rest_api.md
+++ b/rest_api.md
@@ -59,6 +59,8 @@ From time to time Crossref needs to impose rate limits to ensure that the free A
 
 The API is generally RESTFUL and returns results in JSON. JSON formats returned by the API are documented [here](https://github.com/CrossRef/rest-api-doc/blob/master/api_format.md).
 
+The API supports HTTP and HTTPS. Examples here are provided using HTTPS.
+
 The API will only work for Crossref DOIs. You can test the registration agency for a DOI using the following route:
 
 `https://api.crossref.org/works/{doi}/agency`

From 593ae76c902805892467fd9615caf188f79646d0 Mon Sep 17 00:00:00 2001
From: Geoffrey Bilder 
Date: Thu, 27 Apr 2017 07:12:20 +0100
Subject: [PATCH 133/219] document HEAD requests

---
 rest_api.md | 19 +++++++++++++++++--
 1 file changed, 17 insertions(+), 2 deletions(-)

diff --git a/rest_api.md b/rest_api.md
index 7a4035f..570dee4 100644
--- a/rest_api.md
+++ b/rest_api.md
@@ -37,6 +37,7 @@
 - v32, 2016-10-27, document rate limit headers
 - v33, 2016-11-07, guidance on when to use `offset` vs `cursor`
 - v34, 2017-04-26, document support for HTTPS. Update examples to use HTTPS.
+- v35, 2017-04-26, document use of head reqeusts to determine `existence`
 
 ## Background
 
@@ -45,7 +46,6 @@ See the document, [Crossref metadata best practice to support key performance in
 ## Reporting issues, requesting features
 
 Please report problems with the API or the documentation on our [issue tracker](https://github.com/CrossRef/rest-api-doc/issues).
- 
 
 ## License
 
@@ -92,11 +92,14 @@ If you use any of the API calls listed below with a non-Crossref DOI, you will g
 
 ## Results Overview
 
-All results are returned in JSON. There are two general types of results:
+All results are returned in JSON. There are three general types of results:
+
 
 - Singletons
+- Headers-only
 - Lists
 
+
 The mime-type for API results is `application/vnd.crossref-api-message+json` 
 
 
@@ -104,6 +107,18 @@ The mime-type for API results is `application/vnd.crossref-api-message+json`
 
 Singletons are single results. Retrieving metadata for a specific identifier (e.g. DOI, ISSN, funder_identifier) typically returns in a singleton result.
 
+### Headers-only
+
+You can use HTTP HEAD requests to quickly determine "existence" of a singleton. The advantage of this technique is that it is very fast because it does not return any metadata- it only retruns headers and an HTTP status code (200=exists, 404=does not exist).
+
+To determine if member ID `98` exists:
+
+`curl --head "http://api.crossref.org/members/98"`
+
+To determine if a journal with ISSN `1549-7712` exists:
+
+`curl --head "http://api.crossref.org/journals/1549-7712"`
+
 ### Lists
 Lists results can contain multiple entries. Searching or filtering typically returns a list result. A list has two parts:
 

From 8f12314cb0642c9786e739639e003bc474eb258e Mon Sep 17 00:00:00 2001
From: Geoffrey Bilder 
Date: Thu, 27 Apr 2017 08:27:04 +0100
Subject: [PATCH 134/219] replace license route examples with facet/filter
 examples

---
 rest_api.md       | 13 +++++++------
 rest_api_koans.md | 10 +++++-----
 rest_api_tour.md  |  9 +++++----
 3 files changed, 17 insertions(+), 15 deletions(-)

diff --git a/rest_api.md b/rest_api.md
index 570dee4..9581ac1 100644
--- a/rest_api.md
+++ b/rest_api.md
@@ -38,6 +38,7 @@
 - v33, 2016-11-07, guidance on when to use `offset` vs `cursor`
 - v34, 2017-04-26, document support for HTTPS. Update examples to use HTTPS.
 - v35, 2017-04-26, document use of head reqeusts to determine `existence`
+- v36, 2017-04-27, fixed license route examples to use facet/filter instead
 
 ## Background
 
@@ -424,15 +425,15 @@ Note that when you use the `sample` parameter, the `rows` and `offset` parameter
 
 **All works funded by `10.13039/100000001` that have a CC-BY license**
 
-    https://api.crossref.org/funders/10.13039/100000001/works?filter=license.url:https://creativecommons.org/licenses/by/3.0/deed.en_US
+    https://api.crossref.org/funders/10.13039/100000001/works?filter=license.url:http://creativecommons.org/licenses/by/3.0/
 
-**All works published by owner prefix 10.5555 from February 2010 to February 2013 that have a CC-BY license**
+**All works published by owner prefix 10.6064 from February 2010 to February 2013 that have a CC-BY license**
 
-    https://api.crossref.org/prefixes/10.5555/works?filter=license.url:https://creativecommons.org/licenses/by/3.0/deed.en_US,from-pub-date:2010-02,until-pub-date:2013-02
+    https://api.crossref.org/prefixes/10.6064/works?filter=license.url:http://creativecommons.org/licenses/by/3.0/,from-pub-date:2010-02,until-pub-date:2013-02
 
 **All works funded by `10.13039/100000015` where license = CC-BY and embargo <= 365 days**
 
-    https://api.crossref.org/funders/10.13039/100000015/works?filter=license.url:https://creativecommons.org/licenses/by/3.0/deed.en_US,license.delay:365
+    https://api.crossref.org/funders/10.13039/100000015/works?filter=license.url:http://creativecommons.org/licenses/by/3.0/,license.delay:365
 
 Note that the filters for license URL and maximum license embargo period (license.url and license.delay) combine to filter each document's metadata for a license with both of these properties.
 
@@ -446,11 +447,11 @@ Note that the filters for license URL and maximum license embargo period (licens
     
 **All licenses linked to works published by Elsevier**
 
-    https://api.crossref.org/licenses?filter=member:78
+    http://api.crossref.org/v1/works?facet=license:*&filter=member:78&rows=0
     
 **All licenses applied to works published in the journal `Pathology Research International`**
 
-    https://api.crossref.org/licenses?filter=issn:2090-8091
+    https://api.crossref.org/works?facet=license:*&filter=issn:2090-8091
     
 **All works with an award numbered roughly `1 F31 MH11745` also awarded by funder with ID `10.13039/100000025`:
 
diff --git a/rest_api_koans.md b/rest_api_koans.md
index 84e5d82..87d98ab 100644
--- a/rest_api_koans.md
+++ b/rest_api_koans.md
@@ -4,6 +4,7 @@
 
 - V1: 2014-02-26, first draft.
 - V2: 2014-02-28, added license examples
+- V3: 2017-04-27, replace license route examples with facet/filter examples
 
 ## Overview
 
@@ -147,7 +148,7 @@ though once you have a member ID ('98', in this case), you should use that inste
     
 ## What license types does Elsevier support?
 
-    http://api.crossref.org/licenses?filter=member:78
+    http://api.crossref.org/works?facet=license:*&filter=member:78&rows=0
 
 ## Overview of Hindawi's particpation in CrossRef
 
@@ -171,16 +172,15 @@ though once you have a member ID ('98', in this case), you should use that inste
     
 ## What license types does Hindawi support?
 
-    http://api.crossref.org/licenses?filter=member:98
+    http://api.crossref.org/works?facet=license:*&filter=member:98&rows=0
     
 ## What license type does the journal with a particular ISSN support
 
-    http://api.crossref.org/licenses?filter=issn:2090-8091
+    http://api.crossref.org/works?facet=license:*&filter=issn:2090-8091
 
 ## What licenses does a researcher with a particular ORCID publish under
 
-    http://api.crossref.org/licenses?filter=orcid:0000-0003-1340-5202
-
+    http://api.crossref.org/works?facet=license:*&filter=orcid:0000-0003-1340-5202
 
 
 
diff --git a/rest_api_tour.md b/rest_api_tour.md
index c8f6f43..11fa9e2 100644
--- a/rest_api_tour.md
+++ b/rest_api_tour.md
@@ -4,6 +4,7 @@
 
 - V1: 2014-04-18, first draft.
 - V2: 2014-11-10, edits for CR workshop 
+- v3: 2017-04-27, fix license examples
 
 ## Overview
 
@@ -169,16 +170,16 @@ How many Elsevier works have full text links
 
 What license types does Elsevier support?
 
-    http://api.crossref.org/licenses?filter=member:78
+    http://api.crossref.org/works?facet=license:*&filter=member:78
 
 What license types does Hindawi support?
 
-    http://api.crossref.org/licenses?filter=member:98
+    http://api.crossref.org/works?facet=license:*&filter=member:98
 
 What license type does the journal with a particular ISSN support
 
-    http://api.crossref.org/licenses?filter=issn:2090-8091
+    http://api.crossref.org/works?facet=license:*&filter=issn:2090-8091
 
 What licenses does a reasearcher with a particular ORCID publish under
 
-    http://api.crossref.org/licenses?filter=orcid:0000-0003-1340-5202
+    http://api.crossref.org/works?facet=license:*&filter=orcid:0000-0003-1340-5202

From 1dd8fa68dc863e3abac229e729d8a42d0ef3234f Mon Sep 17 00:00:00 2001
From: Karl Jonathan Ward 
Date: Thu, 27 Apr 2017 15:13:58 +0100
Subject: [PATCH 135/219] Mention query.bibliographic

---
 rest_api.md | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/rest_api.md b/rest_api.md
index 9581ac1..6445783 100644
--- a/rest_api.md
+++ b/rest_api.md
@@ -39,6 +39,7 @@
 - v34, 2017-04-26, document support for HTTPS. Update examples to use HTTPS.
 - v35, 2017-04-26, document use of head reqeusts to determine `existence`
 - v36, 2017-04-27, fixed license route examples to use facet/filter instead
+- v37, 2017-04-27, `query.bibliographic`
 
 ## Background
 
@@ -252,6 +253,7 @@ These field queries are available on the `/works` route:
 | `query.chair` | Query chair first and given names |
 | `query.translator` | Query translator first and given names |
 | `query.contributor` | Query author, editor, chair and translator first and given names |
+| `query.bibliographic` | Query bibliographic infomration, useful for citation look up. Includes titles, authors, ISSNs and publication years |
 
 ## Sorting
 

From dfbec27cc8687d13fd941bbb00d28d41a62f4f26 Mon Sep 17 00:00:00 2001
From: Karl Jonathan Ward 
Date: Thu, 27 Apr 2017 15:26:10 +0100
Subject: [PATCH 136/219] New filters and sort fields

---
 rest_api.md | 25 ++++++++++++++++++++++++-
 1 file changed, 24 insertions(+), 1 deletion(-)

diff --git a/rest_api.md b/rest_api.md
index 6445783..a046231 100644
--- a/rest_api.md
+++ b/rest_api.md
@@ -40,6 +40,7 @@
 - v35, 2017-04-26, document use of head reqeusts to determine `existence`
 - v36, 2017-04-27, fixed license route examples to use facet/filter instead
 - v37, 2017-04-27, `query.bibliographic`
+- v38, 2017-04-27, Add v1.1 filters and sort fields
 
 ## Background
 
@@ -268,6 +269,11 @@ sorted. Possible values are:
 | `deposited` | Sort by time of most recent deposit |
 | `indexed` | Sort by time of most recent index |
 | `published` | Sort by publication date |
+| `published-print` | Sort by print publication date |
+| `published-online` | Sort by online publication date |
+| `issued` | Sort by issued date (earliest known publication date) |
+| `is-referenced-by-count` | Sort by number of references to documents |
+| `references-count` | Sort by number of references made by documents |
 
 An example that sorts results in order of publication, beginning with the least recent:
 
@@ -298,6 +304,14 @@ Filters allow you to narrow queries. All filter results are lists.  The followin
 | `until-created-date` | `{date}` | metadata first deposited before (inclusive) `{date}` |
 | `from-pub-date` | `{date}` | metadata where published date is since (inclusive) `{date}` |
 | `until-pub-date` | `{date}` | metadata where published date is before (inclusive)  `{date}` |
+| `from-online-pub-date` | `{date}` | metadata where online published date is since (inclusive) `{date}` |
+| `until-online-pub-date` | `{date}` | metadata where online published date is before (inclusive)  `{date}` |
+| `from-print-pub-date` | `{date}` | metadata where print published date is since (inclusive) `{date}` |
+| `until-print-pub-date` | `{date}` | metadata where print published date is before (inclusive)  `{date}` |
+| `from-posted-date` | `{date}` | metadata where posted date is since (inclusive) `{date}` |
+| `until-posted-date` | `{date}` | metadata where posted date is before (inclusive)  `{date}` |
+| `from-accepted-date` | `{date}` | metadata where accepted date is since (inclusive) `{date}` |
+| `until-accepted-date` | `{date}` | metadata where accepted date is before (inclusive)  `{date}` |
 | `has-license` | | metadata that includes any `` elements. |
 | `license.url` | `{url}` | metadata where `` value equals `{url}` |
 | `license.version` | `{string}` | metadata where the ``'s `applies_to` attribute  is `{string}`|
@@ -305,11 +319,11 @@ Filters allow you to narrow queries. All filter results are lists.  The followin
 | `has-full-text` |  | metadata that includes any full text `` elements. |
 | `full-text.version` | `{string}`  | metadata where `` element's `content_version` attribute is `{string}`. |
 | `full-text.type` | `{mime_type}`  | metadata where `` element's `content_type` attribute is `{mime_type}` (e.g. `application/pdf`). |
-| `public-references` | | metadata where publishers allow references to be distributed publically. [^*] |
 | `has-references` | | metadata for works that have a list of references |
 | `has-archive` | | metadata which include name of archive partner |
 | `archive` | `{string}` | metadata which where value of archive partner is `{string}` |
 | `has-orcid` | | metadata which includes one or more ORCIDs |
+| `has-authenticated-orcid` | | metadata which includes one or more ORCIDs where the depositing publisher claims to have witness the ORCID owner authenticate with ORCID |
 | `orcid` | `{orcid}` | metadata where `` element's value = `{orcid}` |
 | `issn` | `{issn}` | metadata where record has an ISSN = `{issn}`. Format is `xxxx-xxxx`. |
 | `type` | `{type}` | metadata records whose type = `{type}`. Type must be an ID value from the list of types returned by the `/types` resource |
@@ -321,9 +335,11 @@ Filters allow you to narrow queries. All filter results are lists.  The followin
 | `container-title` | | metadata for records with a publication title exactly with an exact match |
 | `publisher-name` | | metadata for records with an exact matching publisher name |
 | `category-name` | | metadata for records with an exact matching category label. Category labels come from [this list](https://www.elsevier.com/solutions/scopus/content) published by Scopus |
+| `type` | | metadata for records with type matching a type identifier (e.g. `journal-article`) |
 | `type-name` | | metadata for records with an exacty matching type label |
 | `award.number` | `{award_number}` | metadata for records with a matching award nunber. Optionally combine with `award.funder` |
 | `award.funder` | `{funder doi or id}` | metadata for records with an award with matching funder. Optionally combine with `award.number` |
+| `has-assertion` | | metadata for records with any assertions |
 | `assertion-group` | | metadata for records with an assertion in a particular group |
 | `assertion` | | metadata for records with a particular named assertion |
 | `affiliation` | | metadata for records with at least one contributor with the given affiliation |
@@ -332,6 +348,13 @@ Filters allow you to narrow queries. All filter results are lists.  The followin
 | `article-number` | | metadata for records with a given article number |
 | `has-abstract` | | metadata for records which include an abstract |
 | `has-clinical-trial-number` | | metadata for records which include a clinical trial number |
+| `content-domain` | | metadata where the publisher records a particular domain name as the location Crossmark content will appear |
+| `has-content-domain` | | metadata where the publisher records a domain name location for Crossmark content |
+| `has-crossmark-restriction` | | metadata where the publisher restricts Crossmark usage to content domains |
+| `has-relation` | | metadata for records that either assert or are the object of a relation |
+| `relation.type` | | One of the relation types from the Crossref relations schema (e.g. `is-referenced-by`, `is-parent-of`, `is-preprint-of`) |
+| `relation.object` | | Relations where the object identifier matches the identifier provided |
+| `relation.object-type` | | One of the identifier types from the Crossref relations schema (e.g. `doi`, `issn`) |
 
 ### Multiple filters
 

From a0e0d9b9fca62fdb4ba05d49f23ca13b2412addd Mon Sep 17 00:00:00 2001
From: Karl Jonathan Ward 
Date: Thu, 27 Apr 2017 15:29:24 +0100
Subject: [PATCH 137/219] Remove mention of dismay

---
 rest_api.md | 14 ++++++--------
 1 file changed, 6 insertions(+), 8 deletions(-)

diff --git a/rest_api.md b/rest_api.md
index a046231..9665988 100644
--- a/rest_api.md
+++ b/rest_api.md
@@ -41,6 +41,7 @@
 - v36, 2017-04-27, fixed license route examples to use facet/filter instead
 - v37, 2017-04-27, `query.bibliographic`
 - v38, 2017-04-27, Add v1.1 filters and sort fields
+- v39, 2017-04-27, Remove mention of dismax
 
 ## Background
 
@@ -97,15 +98,12 @@ If you use any of the API calls listed below with a non-Crossref DOI, you will g
 
 All results are returned in JSON. There are three general types of results:
 
-
 - Singletons
 - Headers-only
 - Lists
 
-
 The mime-type for API results is `application/vnd.crossref-api-message+json` 
 
-
 ### Singletons
 
 Singletons are single results. Retrieving metadata for a specific identifier (e.g. DOI, ISSN, funder_identifier) typically returns in a singleton result.
@@ -126,9 +124,11 @@ To determine if a journal with ISSN `1549-7712` exists:
 Lists results can contain multiple entries. Searching or filtering typically returns a list result. A list has two parts:
 
 - Summary, which include the following information:
+
     - status (e.g. "ok", error)
     - message-type (e.g. "work-list" )
     - message-version (e.g. 1.0.0 )
+    
 - Items, which will will contain the items matching the query or filter. 
 
 Note that the "message-type" returned will differ from the mime-type:
@@ -143,6 +143,7 @@ Note that the "message-type" returned will differ from the mime-type:
 - member-list (list)
 
 Normally, an API list result will return both the summary and the items. If you want to just retrieve the summary, you can do so by specifying that the number of rows returned should be zero. 
+
 ### Sort order
 
 If the API call includes a query, then the sort order will be by the relevance score. If no query is included, then the sort order will be by DOI update date.
@@ -221,12 +222,9 @@ Multiple filters can be specified by separating name:value pairs with a comma:
 
 ## Queries
 
-Queries support a subset of [DisMax](https://wiki.apache.org/solr/DisMax), so, for example you 
-can refine queries as follows.
-
-Works that include "renear" but not "ontologies":
+Free form search queries can be made, for example, works that include `renear` and `ontologies`:
 
-    https://api.crossref.org/works?query=renear+-ontologies
+    https://api.crossref.org/works?query=renear+ontologies
 	
 ## Field Queries
 

From 21ce8c457333ace3238dac51704653c2c9e7bec1 Mon Sep 17 00:00:00 2001
From: Karl Jonathan Ward 
Date: Thu, 27 Apr 2017 15:31:10 +0100
Subject: [PATCH 138/219] Remove link to old background document

---
 rest_api.md | 4 ----
 1 file changed, 4 deletions(-)

diff --git a/rest_api.md b/rest_api.md
index 9665988..934c7aa 100644
--- a/rest_api.md
+++ b/rest_api.md
@@ -43,10 +43,6 @@
 - v38, 2017-04-27, Add v1.1 filters and sort fields
 - v39, 2017-04-27, Remove mention of dismax
 
-## 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.
-
 ## Reporting issues, requesting features
 
 Please report problems with the API or the documentation on our [issue tracker](https://github.com/CrossRef/rest-api-doc/issues).

From a92e1513c15928fb5d2d0c557d0ddb34e9ebd5d8 Mon Sep 17 00:00:00 2001
From: Karl Jonathan Ward 
Date: Thu, 27 Apr 2017 15:37:35 +0100
Subject: [PATCH 139/219] Update faceting documentation

---
 rest_api.md | 34 +++++++++++++++++++++++++++++-----
 1 file changed, 29 insertions(+), 5 deletions(-)

diff --git a/rest_api.md b/rest_api.md
index 934c7aa..0178d98 100644
--- a/rest_api.md
+++ b/rest_api.md
@@ -42,6 +42,7 @@
 - v37, 2017-04-27, `query.bibliographic`
 - v38, 2017-04-27, Add v1.1 filters and sort fields
 - v39, 2017-04-27, Remove mention of dismax
+- v40, 2017-04-27, Clarify faceting feature
 
 ## Reporting issues, requesting features
 
@@ -104,7 +105,7 @@ The mime-type for API results is `application/vnd.crossref-api-message+json`
 
 Singletons are single results. Retrieving metadata for a specific identifier (e.g. DOI, ISSN, funder_identifier) typically returns in a singleton result.
 
-### Headers-only
+### Headers Only
 
 You can use HTTP HEAD requests to quickly determine "existence" of a singleton. The advantage of this technique is that it is very fast because it does not return any metadata- it only retruns headers and an HTTP status code (200=exists, 404=does not exist).
 
@@ -198,14 +199,14 @@ Parameters can be used to query, filter and control the results returned by the
 
 | parameter                    | description                 |
 |:-----------------------------|:----------------------------|
-| `query`                      | limited [DisMax](https://wiki.apache.org/solr/DisMax) query terms |
+| `query`                      | query terms |
 | `filter={filter_name}:{value}`| filter results by specific fields |
 | `rows={#}`                   | results per per page | 
 | `offset={#}` (mak 10k)               | result offset (user `cursor` for larger `/works` result sets)  |                         
 | `sample={#}`                 | return random N results |
 | `sort={#}`                   | sort results by a certain field |
 | `order={#}`                  | set the sort order to `asc` or `desc` |
-| `facet=t`                    | enable facet information in responses |
+| `facet={#}`                    | enable facet information in responses |
 | `cursor={#}`		       | deep page through `/works` result sets |
 
 Multiple filters can be specified by separating name:value pairs with a comma:
@@ -275,8 +276,31 @@ An example that sorts results in order of publication, beginning with the least
 
 ## Facet Counts
 
-Facet counts can be retrieved by enabling faceting; `facet=t` (or `1`, `true`). Facet counts
-give counts per field value for an entire result set.
+Facet counts can be retrieved by enabling faceting. Facets are enabled by providing facet field names along with a maximum number of returned term values. The larger the number of returned values, the longer the query will take. Some facet fields
+can accept a `*` as their maximum, which indicates that all values should be returned.
+
+Facets are specified with the `facet` parameter:
+
+    https://api.crossref.org/works?rows=0&facet=type-name:*
+    
+| Facet name |
+|:-----------|
+| affiliation |
+| funder-name |
+| funder-doi |
+| orcid |
+| container-title |
+| assertion |
+| archive |
+| update-type |
+| issn |
+| published |
+| type-name |
+| publisher-name |
+| license |
+| category-name |
+| relation-type |
+| assertion-group |
 
 ## Filter Names
 

From 748f1d246e72a03c9ac737c55e010fb8531e4bd3 Mon Sep 17 00:00:00 2001
From: Karl Jonathan Ward 
Date: Thu, 27 Apr 2017 15:43:17 +0100
Subject: [PATCH 140/219] Include facet maximum values

---
 rest_api.md | 37 +++++++++++++++++++------------------
 1 file changed, 19 insertions(+), 18 deletions(-)

diff --git a/rest_api.md b/rest_api.md
index 0178d98..4dbfa55 100644
--- a/rest_api.md
+++ b/rest_api.md
@@ -283,24 +283,25 @@ Facets are specified with the `facet` parameter:
 
     https://api.crossref.org/works?rows=0&facet=type-name:*
     
-| Facet name |
-|:-----------|
-| affiliation |
-| funder-name |
-| funder-doi |
-| orcid |
-| container-title |
-| assertion |
-| archive |
-| update-type |
-| issn |
-| published |
-| type-name |
-| publisher-name |
-| license |
-| category-name |
-| relation-type |
-| assertion-group |
+| Facet name | Maximum values |
+|:-----------|:---------------|
+| `affiliation` | `*` |
+| `year` | `*` |
+| `funder-name` | `*` |
+| `funder-doi` | `*` |
+| `orcid` | 100 |
+| `container-title` | 100 |
+| `assertion` | `*` |
+| `archive` | `*` |
+| `update-type` |
+| `issn` | 100 |
+| `published` | `*` |
+| `type-name` | `*` |
+| `publisher-name` | 100 |
+| `license` | `*` |
+| `category-name` | `*` |
+| `relation-type` | `*` |
+| `assertion-group` | `*` |
 
 ## Filter Names
 

From ec11d1f2c5be98d431fb3ee12c647d53ad5cd6f2 Mon Sep 17 00:00:00 2001
From: Karl Jonathan Ward 
Date: Thu, 27 Apr 2017 15:46:16 +0100
Subject: [PATCH 141/219] Change documentation of accessing versions

---
 rest_api.md | 18 +++++-------------
 1 file changed, 5 insertions(+), 13 deletions(-)

diff --git a/rest_api.md b/rest_api.md
index 4dbfa55..237b31a 100644
--- a/rest_api.md
+++ b/rest_api.md
@@ -293,7 +293,7 @@ Facets are specified with the `facet` parameter:
 | `container-title` | 100 |
 | `assertion` | `*` |
 | `archive` | `*` |
-| `update-type` |
+| `update-type` | `*` |
 | `issn` | 100 |
 | `published` | `*` |
 | `type-name` | `*` |
@@ -524,16 +524,8 @@ Adding syntax options or metadata to representations will normally be backwards
 
 ### How to manage API versions
 
-If you need to tie your implementation to a specific major version of the API, you can do so by using content-negotiation and specifying the version of the API in the `ACCEPT` header as follows:
+If you need to tie your implementation to a specific major version of the API, you can do so by using version-specific routes. The default route redirects to the most recent version of the API. Some older major versions may be available using a version prefix. For example, to access version `v1` of the API:
 
-     application/vnd.crossref-api-message+json; version=1.0
-
-Minor version numbers will be ignored in `ACCEPT` headers as they are by definition backwards compatible.
-
-If you omit a specific version in your `ACCEPT` header, the system will default to using the latest version of the API. 
-
-Note that requesting a version of the API via content type is not yet supported.
-
-## Error messages
-
-There will be no errors, and therefor error messages will be unnecessary. But seriously… coming soon.
+    https://api.crossref.orv/v1/works
+    
+Each major version has no backwards incompatible changes within its public interface.

From 41ce576a8e3bfaa234d76c3df377d30f4f353077 Mon Sep 17 00:00:00 2001
From: Karl Jonathan Ward 
Date: Thu, 27 Apr 2017 15:48:04 +0100
Subject: [PATCH 142/219] Clarify versioning semantics

---
 rest_api.md | 19 ++++++++-----------
 1 file changed, 8 insertions(+), 11 deletions(-)

diff --git a/rest_api.md b/rest_api.md
index 237b31a..5b9544c 100644
--- a/rest_api.md
+++ b/rest_api.md
@@ -505,20 +505,17 @@ Note that the filters for license URL and maximum license embargo period (licens
 
 In theory, the syntax of the API can vary independently of the result representations. In practice, major version changes in either will require changes to API clients and so versioning of the API will apply to both the API syntax and the result representation.
 
-The API uses a semantic versioning scheme whereby the version number is divided into three parts delimited by periods. The first number represents the "major" release number. The second represents a "minor" release number and the third represents an "internal" release number.  
+The API uses a semantic versioning scheme whereby the version number is divided into three parts delimited by periods. The first number represents the "major" release number. The second represents a "minor" release number.
       
-    Version 1.20.31
-            ^  ^  ^
-            |  |  |
-        major  |  |
-           minor  |
-           internal
+    Version 1.20
+            ^  ^
+            |  |
+        major  |
+           minor
 
- **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.
-
-**Internal** version increments are simply used to keep track of development versions of the API. They should never have any effect on client applications.
+**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, and Crossref will only maintain the latest minor version for the two most recent major versions.
 
 Adding syntax options or metadata to representations will normally be backwards compatible and will thus normally only trigger minor version changes. Renaming or restructuring syntax options of metadata tends not to be backward compatible and will thus typically trigger major version changes
 

From 4cd5f73dde9e1b0e1c8f767b05e113793b7dc81e Mon Sep 17 00:00:00 2001
From: Geoffrey Bilder 
Date: Fri, 28 Apr 2017 08:22:20 +0100
Subject: [PATCH 143/219] document `sample` max = 100, clarify cursors only
 work on some routes

---
 rest_api.md | 27 +++++++++++++++------------
 1 file changed, 15 insertions(+), 12 deletions(-)

diff --git a/rest_api.md b/rest_api.md
index 5b9544c..dbfc916 100644
--- a/rest_api.md
+++ b/rest_api.md
@@ -26,13 +26,13 @@
 - 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.
-- 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
-- v28, 2016-05-09, Added link to source of category lables
-- v29, 2016-05-24, Added field queries
-- v30, 2016-09-26, Highlight issue tracker
+- 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
+- v28, 2016-05-09, added link to source of category lables
+- v29, 2016-05-24, added field queries
+- v30, 2016-09-26, highlight issue tracker
 - v31, 2016-10-05, document `has-clinical-trial-number` and `has-abstract` filters
 - v32, 2016-10-27, document rate limit headers
 - v33, 2016-11-07, guidance on when to use `offset` vs `cursor`
@@ -40,9 +40,10 @@
 - v35, 2017-04-26, document use of head reqeusts to determine `existence`
 - v36, 2017-04-27, fixed license route examples to use facet/filter instead
 - v37, 2017-04-27, `query.bibliographic`
-- v38, 2017-04-27, Add v1.1 filters and sort fields
-- v39, 2017-04-27, Remove mention of dismax
-- v40, 2017-04-27, Clarify faceting feature
+- v38, 2017-04-27, add v1.1 filters and sort fields
+- v39, 2017-04-27, remove mention of dismax
+- v40, 2017-04-27, clarify faceting feature
+- v41, 2017-04028, document `sample` max = 100, clarify cursors only work on some routes 
 
 ## Reporting issues, requesting features
 
@@ -203,7 +204,7 @@ Parameters can be used to query, filter and control the results returned by the
 | `filter={filter_name}:{value}`| filter results by specific fields |
 | `rows={#}`                   | results per per page | 
 | `offset={#}` (mak 10k)               | result offset (user `cursor` for larger `/works` result sets)  |                         
-| `sample={#}`                 | return random N results |
+| `sample={#}` (max 100)                | return random N results |
 | `sort={#}`                   | sort results by a certain field |
 | `order={#}`                  | set the sort order to `asc` or `desc` |
 | `facet={#}`                    | enable facet information in responses |
@@ -416,7 +417,9 @@ every time there is a change to metadata requiring a reindex.
 
 ## Result controls
 
-You can control the delivery and selection results using the `rows`, `offset` and `sample` parameters. If you are expecting results beyond 10K, then use a `cursor` to deep page through the results. 
+You can control the delivery and selection results using the `rows`, `offset` and `sample` parameters.
+
+ If you are expecting results beyond 10K, then use a `cursor` to deep page through the results. Note that not all routes support cursors.
 
 ### Rows 
 

From a0018310d8be490d4203857f32d93d2aa4d05787 Mon Sep 17 00:00:00 2001
From: Geoffrey Bilder 
Date: Fri, 28 Apr 2017 08:33:17 +0100
Subject: [PATCH 144/219] reminder on the wisdom of url-encoding

---
 rest_api.md | 8 +++++++-
 1 file changed, 7 insertions(+), 1 deletion(-)

diff --git a/rest_api.md b/rest_api.md
index dbfc916..c73447f 100644
--- a/rest_api.md
+++ b/rest_api.md
@@ -43,7 +43,9 @@
 - v38, 2017-04-27, add v1.1 filters and sort fields
 - v39, 2017-04-27, remove mention of dismax
 - v40, 2017-04-27, clarify faceting feature
-- v41, 2017-04028, document `sample` max = 100, clarify cursors only work on some routes 
+- v41, 2017-04-28, document `sample` max = 100, clarify cursors only work on some routes
+- v42, 2017-04-28, life the universe and everything
+- v43, 2017-04-28, reminder on the wisdom of url-encoding
 
 ## Reporting issues, requesting features
 
@@ -63,6 +65,10 @@ The API is generally RESTFUL and returns results in JSON. JSON formats returned
 
 The API supports HTTP and HTTPS. Examples here are provided using HTTPS.
 
+You should always url-encode DOIs and parameter values when using the API. DOIs are notorious for including characters that break URLs (e.g. semicolons, hashes, slashes, ampersands, question marks, etc.).
+
+Note that, for the sake of clarity, the examples in this document do *not* url-encode DOIs or parameter values. 
+
 The API will only work for Crossref DOIs. You can test the registration agency for a DOI using the following route:
 
 `https://api.crossref.org/works/{doi}/agency`

From e3606c0dcc09efc581d7e4a279fca20a04cfe5af Mon Sep 17 00:00:00 2001
From: Geoffrey Bilder 
Date: Fri, 28 Apr 2017 08:33:47 +0100
Subject: [PATCH 145/219] punctuation

---
 rest_api.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/rest_api.md b/rest_api.md
index c73447f..a867924 100644
--- a/rest_api.md
+++ b/rest_api.md
@@ -44,7 +44,7 @@
 - v39, 2017-04-27, remove mention of dismax
 - v40, 2017-04-27, clarify faceting feature
 - v41, 2017-04-28, document `sample` max = 100, clarify cursors only work on some routes
-- v42, 2017-04-28, life the universe and everything
+- v42, 2017-04-28, life, the universe, and everything
 - v43, 2017-04-28, reminder on the wisdom of url-encoding
 
 ## Reporting issues, requesting features

From b8ca0154aec943bc904251004153f256a9ac144d Mon Sep 17 00:00:00 2001
From: Geoffrey Bilder 
Date: Fri, 28 Apr 2017 10:22:09 +0100
Subject: [PATCH 146/219] clarify that field queries apply to `/works` route.

---
 rest_api.md | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/rest_api.md b/rest_api.md
index a867924..c415761 100644
--- a/rest_api.md
+++ b/rest_api.md
@@ -46,6 +46,7 @@
 - v41, 2017-04-28, document `sample` max = 100, clarify cursors only work on some routes
 - v42, 2017-04-28, life, the universe, and everything
 - v43, 2017-04-28, reminder on the wisdom of url-encoding
+- v44, 2017-04028, clarify that field queries apply to `/works` route
 
 ## Reporting issues, requesting features
 
@@ -232,7 +233,7 @@ Free form search queries can be made, for example, works that include `renear` a
 	
 ## Field Queries
 
-Field queries are available on some routes and allow for queries that match only particular fields
+Field queries are available on the `/works` route and allow for queries that match only particular fields
 of metadata. For example, this query matches records that contain the tokens `richard` or `feynman` (or both)
 in any author field:
 

From 091ebf25f950cecfcadb829da461e9d8cb3d1ee8 Mon Sep 17 00:00:00 2001
From: Geoffrey Bilder 
Date: Fri, 28 Apr 2017 11:32:53 +0100
Subject: [PATCH 147/219] document `location` filter for `/funders` route

---
 rest_api.md | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/rest_api.md b/rest_api.md
index c415761..91c99b9 100644
--- a/rest_api.md
+++ b/rest_api.md
@@ -46,7 +46,8 @@
 - v41, 2017-04-28, document `sample` max = 100, clarify cursors only work on some routes
 - v42, 2017-04-28, life, the universe, and everything
 - v43, 2017-04-28, reminder on the wisdom of url-encoding
-- v44, 2017-04028, clarify that field queries apply to `/works` route
+- v44, 2017-04-28, clarify that field queries apply to `/works` route
+- v45, 2017-04-28, document `location` filter for `/funders` route
 
 ## Reporting issues, requesting features
 
@@ -319,6 +320,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 |
+| `location` |`{country name}` | funder records where location = `{country name}`. Only works on `/funders` route |
 | `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 |
 | `from-index-date` | `{date}` | metadata indexed since (inclusive) `{date}` |

From 3e91bc41bc170749d0edf7d00c3f396703d4617d Mon Sep 17 00:00:00 2001
From: Geoffrey Bilder 
Date: Fri, 28 Apr 2017 11:34:02 +0100
Subject: [PATCH 148/219] snake-case

---
 rest_api.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/rest_api.md b/rest_api.md
index 91c99b9..766ca71 100644
--- a/rest_api.md
+++ b/rest_api.md
@@ -320,7 +320,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 |
-| `location` |`{country name}` | funder records where location = `{country name}`. Only works on `/funders` route |
+| `location` |`{country_name}` | funder records where location = `{country name}`. Only works on `/funders` route |
 | `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 |
 | `from-index-date` | `{date}` | metadata indexed since (inclusive) `{date}` |

From b3eeca6ec2c1095ba1e8eb722c56ca7170e2e8ad Mon Sep 17 00:00:00 2001
From: Karl Jonathan Ward 
Date: Sun, 30 Apr 2017 17:04:30 +0100
Subject: [PATCH 149/219] Describe facet fields

---
 rest_api.md | 38 +++++++++++++++++++-------------------
 1 file changed, 19 insertions(+), 19 deletions(-)

diff --git a/rest_api.md b/rest_api.md
index 766ca71..79ff16d 100644
--- a/rest_api.md
+++ b/rest_api.md
@@ -292,25 +292,25 @@ Facets are specified with the `facet` parameter:
 
     https://api.crossref.org/works?rows=0&facet=type-name:*
     
-| Facet name | Maximum values |
-|:-----------|:---------------|
-| `affiliation` | `*` |
-| `year` | `*` |
-| `funder-name` | `*` |
-| `funder-doi` | `*` |
-| `orcid` | 100 |
-| `container-title` | 100 |
-| `assertion` | `*` |
-| `archive` | `*` |
-| `update-type` | `*` |
-| `issn` | 100 |
-| `published` | `*` |
-| `type-name` | `*` |
-| `publisher-name` | 100 |
-| `license` | `*` |
-| `category-name` | `*` |
-| `relation-type` | `*` |
-| `assertion-group` | `*` |
+| Facet name | Maximum values | Description |
+|:-----------|:---------------|-------------|
+| `affiliation` | `*` | Author affiliation | 
+| `year` | `*` | Earliest year of publication, synonym for `published` |
+| `funder-name` | `*` | Funder literal name as deposited alongside DOIs |
+| `funder-doi` | `*` | Funder DOI |
+| `orcid` | 100 | Contributor ORCID | 
+| `container-title` | 100 | Work container title, such as journal title, or book title |
+| `assertion` | `*` | Custom Crossmark assertion name |
+| `archive` | `*` | Archive location |
+| `update-type` | `*` | Significant update type |
+| `issn` | 100 | Journal ISSN (any - print, electronic, link) |
+| `published` | `*` | Earliest year of publication |
+| `type-name` | `*` | Work type name, such as `journal-article` or `book-chapter` |
+| `publisher-name` | 100 | Publisher of work |
+| `license` | `*` | License URI of work |
+| `category-name` | `*` | Category name of work |
+| `relation-type` | `*` | Relation type described by work or described by another work with work as object |
+| `assertion-group` | `*` | Custom Crossmark assertion group name |
 
 ## Filter Names
 

From bc4ca3d49c7354aee82dad51b32d245fd2f49cdf Mon Sep 17 00:00:00 2001
From: Karl Jonathan Ward 
Date: Tue, 2 May 2017 12:54:14 +0100
Subject: [PATCH 150/219] Fix misnaming of some filter fields

---
 deposit_api.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/deposit_api.md b/deposit_api.md
index cba9b33..5c2c757 100644
--- a/deposit_api.md
+++ b/deposit_api.md
@@ -126,8 +126,8 @@ The `/deposits` route also specifies some filters:
 | Filter | Possible Values | Description |
 |--------|-----------------|-------------|
 | status | One of `submitted`, `failed` or `completed` | Return only those deposits with given status |
-| from-submitted-date | Date | Return only those deposits that were deposited on or after the given date |
-| until-submitted-date | Date | Return only those deposits that were deposited on or before the given date |
+| from-submitted-time | Date | Return only those deposits that were deposited on or after the given date |
+| until-submitted-time | Date | Return only those deposits that were deposited on or before the given date |
 | doi | DOI | Return only those deposits that deposited against the given DOI |
 | test | One of `true`, `t`, `1`, `false`, `f`, `0` | Return only those deposits that are or are not test deposits. By default all deposits, both test and live, are returned. |
 | type| Content Type | Return only those deposits with the given content type (mime type) |

From a349aabc9e85a62bb21b105bc419320aa324f2f4 Mon Sep 17 00:00:00 2001
From: 5j9 <5j9@users.noreply.github.com>
Date: Sun, 21 May 2017 21:31:49 +0430
Subject: [PATCH 151/219] Fix typo in api_format.md

Eariest -> Earliest
---
 api_format.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/api_format.md b/api_format.md
index a40c5b3..e237ee5 100644
--- a/api_format.md
+++ b/api_format.md
@@ -21,7 +21,7 @@
 | created | [Date](#date) | Yes | Date on which the DOI was first registered |
 | deposited | [Date](#date) | Yes | Date on which the work metadata was most recently updated |
 | indexed | [Date](#date) | Yes | Date on which the work metadata was most recently indexed. Re-indexing does not imply a metadata change, see `deposited` for the most recent metadata change date |
-| issued | [Partial Date](#partial-date) | Yes | Eariest of `published-print` and `published-online` |
+| issued | [Partial Date](#partial-date) | Yes | Earliest of `published-print` and `published-online` |
 | subtitle | Array of String | No | Work subtitles, including original language and translated |
 | container-title | Array of String | No | Titles (full and abbreviated) of the containing work (usually a book or journal.) |
 | issue | String | No | Issue number of an article's journal |

From f157dd190f4b7233f13f96d5574aa2c1fb3c9062 Mon Sep 17 00:00:00 2001
From: 5j9 <5j9@users.noreply.github.com>
Date: Mon, 22 May 2017 11:12:30 +0430
Subject: [PATCH 152/219] Fix contributor fields

---
 api_format.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/api_format.md b/api_format.md
index a40c5b3..690dc87 100644
--- a/api_format.md
+++ b/api_format.md
@@ -70,8 +70,8 @@
 
 | Field | Type | Required | Description |
 |-------|------|----------|-------------|
-| family-name | String | Yes | |
-| given-name | String | No | |
+| family | String | Yes | |
+| given | String | No | |
 | ORCID | URL | No | URL-form of an [ORCID](http://orcid.org) identifier |
 | affiliation | Array of [Affiliation](#affiliation) | No | |
 

From b59585c5b83f86cd822fb5d3cf0cfb72fb62cbe4 Mon Sep 17 00:00:00 2001
From: 5j9 <5j9@users.noreply.github.com>
Date: Tue, 23 May 2017 18:26:44 +0430
Subject: [PATCH 153/219] Fix typo in the word `support`

---
 rest_api_tour.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/rest_api_tour.md b/rest_api_tour.md
index 11fa9e2..0a6606d 100644
--- a/rest_api_tour.md
+++ b/rest_api_tour.md
@@ -8,7 +8,7 @@
 
 ## Overview
 
-The following short examples show how the CrossRef REST APIs can be used to provide CrossPublisher suport for TDM applications. This demonstration is a bit of a paradox- it is targeted at a  non-technical audience who wants to understand a little but about the technical infrastructure that researchers can leverage for TDM applications.
+The following short examples show how the CrossRef REST APIs can be used to provide CrossPublisher support for TDM applications. This demonstration is a bit of a paradox- it is targeted at a  non-technical audience who wants to understand a little but about the technical infrastructure that researchers can leverage for TDM applications.
 
 ## Technical notes
 

From fadc3e45559f5745be3b3fefc161e8de1a8a6540 Mon Sep 17 00:00:00 2001
From: Karl Jonathan Ward 
Date: Mon, 5 Jun 2017 13:15:48 +0100
Subject: [PATCH 154/219] Remove mention of publisher-name filter

---
 rest_api.md | 4 +---
 1 file changed, 1 insertion(+), 3 deletions(-)

diff --git a/rest_api.md b/rest_api.md
index 79ff16d..b947532 100644
--- a/rest_api.md
+++ b/rest_api.md
@@ -21,7 +21,7 @@
 - v16: 2014-05-19, new `/journals` route, new CrossMark (updates and update policy) filters, new `sort` and `order` parameters
 - v17: 2014-05-19, new `facet` query parameter
 - v18: 2014-05-29, new `/works/{doi}/agency` route
-- v19: 2014-06-23, new textual filters - `container-title`, `publisher-name`, `category-name`.
+- v19: 2014-06-23, new textual filters - `container-title`, `category-name`.
 - v20: 2014-06-24, OR filter queries, `type-name` filter.
 - 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. 
@@ -306,7 +306,6 @@ Facets are specified with the `facet` parameter:
 | `issn` | 100 | Journal ISSN (any - print, electronic, link) |
 | `published` | `*` | Earliest year of publication |
 | `type-name` | `*` | Work type name, such as `journal-article` or `book-chapter` |
-| `publisher-name` | 100 | Publisher of work |
 | `license` | `*` | License URI of work |
 | `category-name` | `*` | Category name of work |
 | `relation-type` | `*` | Relation type described by work or described by another work with work as object |
@@ -362,7 +361,6 @@ Filters allow you to narrow queries. All filter results are lists.  The followin
 | `is-update` | | metadata for records that represent editorial updates |
 | `has-update-policy` | | metadata for records that include a link to an editorial update policy |
 | `container-title` | | metadata for records with a publication title exactly with an exact match |
-| `publisher-name` | | metadata for records with an exact matching publisher name |
 | `category-name` | | metadata for records with an exact matching category label. Category labels come from [this list](https://www.elsevier.com/solutions/scopus/content) published by Scopus |
 | `type` | | metadata for records with type matching a type identifier (e.g. `journal-article`) |
 | `type-name` | | metadata for records with an exacty matching type label |

From 78a1e74643f68e810029a2d5a719067fca6a990c Mon Sep 17 00:00:00 2001
From: kmeddings 
Date: Wed, 14 Jun 2017 12:15:13 +0100
Subject: [PATCH 155/219] minor text changes and new funder registry link

---
 rest_api.md | 29 +++++++++++++++--------------
 1 file changed, 15 insertions(+), 14 deletions(-)

diff --git a/rest_api.md b/rest_api.md
index b947532..8f16b95 100644
--- a/rest_api.md
+++ b/rest_api.md
@@ -48,6 +48,7 @@
 - v43, 2017-04-28, reminder on the wisdom of url-encoding
 - v44, 2017-04-28, clarify that field queries apply to `/works` route
 - v45, 2017-04-28, document `location` filter for `/funders` route
+- v46, 2017-06-14, minor text changes and new funder registry link
 
 ## Reporting issues, requesting features
 
@@ -156,7 +157,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
@@ -170,11 +171,11 @@ These can be used alone like this
 | resource      | description                       |
 |:--------------|:----------------------------------|
 | `/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](https://www.crossref.org/fundref/fundref_registry.html)
-| `/members` | returns a list of all CrossRef members (mostly publishers) |
+| `/funders`    | returns a list of all funders in the [Funder Registry](https://github.com/CrossRef/open-funder-registry
+| `/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
@@ -182,10 +183,10 @@ Resource components can be used in conjunction with identifiers to retrieve the
 
 | 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 |
 
@@ -195,16 +196,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                 |
 |:-----------------------------|:----------------------------|
@@ -406,13 +407,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
 
@@ -525,7 +526,7 @@ The API uses a semantic versioning scheme whereby the version number is divided
 
  **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, and Crossref will only maintain the latest minor version for the two most recent major 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, and Crossref will only maintain the latest minor version for the two most recent major versions.
 
 Adding syntax options or metadata to representations will normally be backwards compatible and will thus normally only trigger minor version changes. Renaming or restructuring syntax options of metadata tends not to be backward compatible and will thus typically trigger major version changes
 

From 76234d4a60501a045281357fc2f688b980c7f6d3 Mon Sep 17 00:00:00 2001
From: kmeddings 
Date: Mon, 19 Jun 2017 15:18:16 +0100
Subject: [PATCH 156/219] Update deposit_api.md

---
 deposit_api.md | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/deposit_api.md b/deposit_api.md
index 5c2c757..d81dbdb 100644
--- a/deposit_api.md
+++ b/deposit_api.md
@@ -1,4 +1,4 @@
-# CrossRef RESTful Deposit API
+# CrossRef RESTful Deposit API (Alpha)
 
 ## Versioning
 
@@ -7,6 +7,8 @@
 | 2014-03-10 | v1 | Initial version |
 | 2015-01-15 | v2 | Mention PDF deposits |
 
+Note: this code is used by the Open Journals System (OJS) integration. It is not intended for use by other Crossref members, who should use the production deposit system at http://doi.crossref.org
+
 ## Background
 
 CrossRef provides a deposit mechanisms for our members and manuscript system vendors.

From a4d047e0d1556e80aaab0f4b5aae420da2a99ea2 Mon Sep 17 00:00:00 2001
From: Karl Jonathan Ward 
Date: Tue, 4 Jul 2017 17:48:34 +0100
Subject: [PATCH 157/219] Clarify query.affiliation (not a filter)

---
 rest_api.md | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/rest_api.md b/rest_api.md
index 8f16b95..3bfd244 100644
--- a/rest_api.md
+++ b/rest_api.md
@@ -49,6 +49,7 @@
 - v44, 2017-04-28, clarify that field queries apply to `/works` route
 - v45, 2017-04-28, document `location` filter for `/funders` route
 - v46, 2017-06-14, minor text changes and new funder registry link
+- v47, 2017-07-04, clarify `query.affiliation`
 
 ## Reporting issues, requesting features
 
@@ -260,6 +261,7 @@ These field queries are available on the `/works` route:
 | `query.translator` | Query translator first and given names |
 | `query.contributor` | Query author, editor, chair and translator first and given names |
 | `query.bibliographic` | Query bibliographic infomration, useful for citation look up. Includes titles, authors, ISSNs and publication years |
+| `query.affiliation` | Query contributor affiliations |
 
 ## Sorting
 
@@ -370,7 +372,6 @@ Filters allow you to narrow queries. All filter results are lists.  The followin
 | `has-assertion` | | metadata for records with any assertions |
 | `assertion-group` | | metadata for records with an assertion in a particular group |
 | `assertion` | | metadata for records with a particular named assertion |
-| `affiliation` | | metadata for records with at least one contributor with the given affiliation |
 | `has-affiliation` | | metadata for records that have any affiliation information |
 | `alternative-id` | | metadata for records with the given alternative ID, which may be a publisher-specific ID, or any other identifier a publisher may have provided |
 | `article-number` | | metadata for records with a given article number |

From def851d648e16d1bde1d6fd87497135d3364b18e Mon Sep 17 00:00:00 2001
From: kmeddings 
Date: Thu, 13 Jul 2017 16:30:12 +0100
Subject: [PATCH 158/219] Correct name terms

---
 rest_api.md | 12 ++++++------
 1 file changed, 6 insertions(+), 6 deletions(-)

diff --git a/rest_api.md b/rest_api.md
index 3bfd244..837d977 100644
--- a/rest_api.md
+++ b/rest_api.md
@@ -50,7 +50,7 @@
 - v45, 2017-04-28, document `location` filter for `/funders` route
 - v46, 2017-06-14, minor text changes and new funder registry link
 - v47, 2017-07-04, clarify `query.affiliation`
-
+- v48, 2017-07-13, correct "first and given" names to "given and family"
 ## Reporting issues, requesting features
 
 Please report problems with the API or the documentation on our [issue tracker](https://github.com/CrossRef/rest-api-doc/issues).
@@ -255,11 +255,11 @@ These field queries are available on the `/works` route:
 |-----------------------|-------------|
 | `query.title` | Query `title` and `subtitle` |
 | `query.container-title` | Query `container-title` aka. publication name |
-| `query.author` | Query author first and given names |
-| `query.editor` | Query editor first and given names |
-| `query.chair` | Query chair first and given names |
-| `query.translator` | Query translator first and given names |
-| `query.contributor` | Query author, editor, chair and translator first and given names |
+| `query.author` | Query author given and family names |
+| `query.editor` | Query editor given and family names |
+| `query.chair` | Query chair given and family names |
+| `query.translator` | Query translator given and family names |
+| `query.contributor` | Query author, editor, chair and translator given and family names |
 | `query.bibliographic` | Query bibliographic infomration, useful for citation look up. Includes titles, authors, ISSNs and publication years |
 | `query.affiliation` | Query contributor affiliations |
 

From d5af907fb763d2e2d95c77af89e0306462b2312f Mon Sep 17 00:00:00 2001
From: kmeddings 
Date: Tue, 18 Jul 2017 16:34:02 +0100
Subject: [PATCH 159/219] Update rest_api.md

---
 rest_api.md | 9 +++++++++
 1 file changed, 9 insertions(+)

diff --git a/rest_api.md b/rest_api.md
index 837d977..6cb3c61 100644
--- a/rest_api.md
+++ b/rest_api.md
@@ -1,5 +1,14 @@
 # Crossref REST API
 
+## What's New
+July 2017
+- References are now included if the publisher has made them public.
+- Metadata for preprints, listed as "posted-content"
+- Links from preprints to subsequent publications using "isPreprintOf" relationship
+- Abstracts for over 1 million DOIs
+- Subject categories have been updated to cover more of the content (~45,000 journal titles)
+- "is-referenced-by-count" - also known as cited-by counts. __NOTE 18 JULY 2017__: cited-by counts are not are not updating and should not be considered accurate. We are working on a fix and will update when it is in place
+ 
 ## Version History
 
 - V1: 2013-09-08, first draft.

From 0ca55f70d71b72c83b5bd5ff92cc833b61b8e796 Mon Sep 17 00:00:00 2001
From: Geoffrey Bilder 
Date: Thu, 20 Jul 2017 11:25:36 +0200
Subject: [PATCH 160/219] major re-org. add TOC

---
 rest_api.md | 223 ++++++++++++++++++++++++++++++++++++----------------
 1 file changed, 155 insertions(+), 68 deletions(-)

diff --git a/rest_api.md b/rest_api.md
index 6cb3c61..05f626e 100644
--- a/rest_api.md
+++ b/rest_api.md
@@ -1,78 +1,111 @@
 # Crossref REST API
 
-## What's New
-July 2017
+
+
+
+
+
+- [Service alert: 18 July 2017](#service-alert-18-july-2017)
+- [What's new: July 2017](#whats-new-july-2017)
+- [Preamble](#preamble)
+- [Meta](#meta)
+- [API overview](#api-overview)
+- [Result types](#result-types)
+- [Resource components](#resource-components)
+- [Parameters](#parameters)
+- [Queries](#queries)
+- [Field Queries](#field-queries)
+- [Sorting](#sorting)
+- [Facet counts](#facet-counts)
+- [Filter names](#filter-names)
+- [Result controls](#result-controls)
+- [Versioning](#versioning)
+- [Documentation history](#documentation-history)
+
+
+
+## Service alert: 18 July 2017
+
+ Cited-by counts are not are not updating and should not be considered accurate. We are working on a fix and will update you ([see below](#learning-about-performanceavialability-problems)) when it is in place.
+
+## What's new: July 2017
+
 - References are now included if the publisher has made them public.
 - Metadata for preprints, listed as "posted-content"
 - Links from preprints to subsequent publications using "isPreprintOf" relationship
 - Abstracts for over 1 million DOIs
 - Subject categories have been updated to cover more of the content (~45,000 journal titles)
-- "is-referenced-by-count" - also known as cited-by counts. __NOTE 18 JULY 2017__: cited-by counts are not are not updating and should not be considered accurate. We are working on a fix and will update when it is in place
- 
-## Version History
+- "is-referenced-by-count" - also known as cited-by counts.
 
-- V1: 2013-09-08, first draft.
-- V2: 2013-09-24, reference platform deployed
-- v3: 2013-09-25, reworked filters. Added API versioning doc 
-- v4: 2013-09-25, more filter changes.
-- v5: 2013-09-27, doc mime-type and message-type relationship
-- v6: 2013-10-01, updated `sample` & added examples with filters
-- v6: 2013-10-01, corrected warning date
-- v7: 2013-10-02, fixed typos
-- v8: 2013-10-17, updated warning. Added email address
-- v9: 2013-12-13, update example urls
-- v10: 2013-12-13, /types routes, type filter, issn filter
-- v11: 2013-12-14, indexed timestamps, has-archive and archive implemented
-- v12: 2014-01-06, directory filter
-- v13: 2014-02-10, new `/members`, `/publishers` becomes `/prefixes`, new `member` filter, `publisher` filter becomes `prefix`
-- v14: 2014-02-14, new `has-funder` filter.
-- v15: 2014-02-27, new `/licenses` route
-- v16: 2014-05-19, new `/journals` route, new CrossMark (updates and update policy) filters, new `sort` and `order` parameters
-- v17: 2014-05-19, new `facet` query parameter
-- v18: 2014-05-29, new `/works/{doi}/agency` route
-- v19: 2014-06-23, new textual filters - `container-title`, `category-name`.
-- v20: 2014-06-24, OR filter queries, `type-name` filter.
-- 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.
-- 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
-- v28, 2016-05-09, added link to source of category lables
-- v29, 2016-05-24, added field queries
-- v30, 2016-09-26, highlight issue tracker
-- v31, 2016-10-05, document `has-clinical-trial-number` and `has-abstract` filters
-- v32, 2016-10-27, document rate limit headers
-- v33, 2016-11-07, guidance on when to use `offset` vs `cursor`
-- v34, 2017-04-26, document support for HTTPS. Update examples to use HTTPS.
-- v35, 2017-04-26, document use of head reqeusts to determine `existence`
-- v36, 2017-04-27, fixed license route examples to use facet/filter instead
-- v37, 2017-04-27, `query.bibliographic`
-- v38, 2017-04-27, add v1.1 filters and sort fields
-- v39, 2017-04-27, remove mention of dismax
-- v40, 2017-04-27, clarify faceting feature
-- v41, 2017-04-28, document `sample` max = 100, clarify cursors only work on some routes
-- v42, 2017-04-28, life, the universe, and everything
-- v43, 2017-04-28, reminder on the wisdom of url-encoding
-- v44, 2017-04-28, clarify that field queries apply to `/works` route
-- v45, 2017-04-28, document `location` filter for `/funders` route
-- v46, 2017-06-14, minor text changes and new funder registry link
-- v47, 2017-07-04, clarify `query.affiliation`
-- v48, 2017-07-13, correct "first and given" names to "given and family"
-## Reporting issues, requesting features
 
-Please report problems with the API or the documentation on our [issue tracker](https://github.com/CrossRef/rest-api-doc/issues).
+## Preamble
+
+The Crossref REST API is one of [a variety of tools and APIs](https://www.crossref.org/services/metadata-delivery/) that allow anybody to search and reuse our members' metadata in sophisticated ways.
+
+
+## Meta
+### Learning about performance or avialability problems
+
+Note that we generally post notice any ongoing performance problems with our services on our twitter feeds at [CrossRefOrg](https://twitter.com/CrossrefOrg) and [CrossRefSupport](https://twitter.com/@CrossrefSupport). We also report them on our [support site](https://support.crossref.org/hc/en-us). You might want to check these to see if we are already aware of a problem before you report it.
+
+### Reporting performance or avialability problems
+
+Report performance/avialability at our [support site](https://support.crossref.org/hc/en-us)
+
+### Reporting bugs, requesting features ###
+
+Please report bugs with the API or the documentation on our [issue tracker](https://github.com/CrossRef/rest-api-doc/issues).
+
+### License
+
 
-## 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.
 
-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](https://www.crossref.org/privacy/).
+### Privacy
 
-## Rate limits
+We also have a [privacy policy](https://www.crossref.org/privacy/).
+
+### Libraries
+
+You might be able to avoid reading all this documentation if you instead use one of the several excellent libraries that have been written for the Crossref REST API. For example:
+
+- [habanero](https://github.com/sckott/habanero) (Python)
+- [serrano](https://github.com/sckott/serrano) (Ruby)
+- [rcrossref](https://github.com/ropensci/rcrossref) (R)
+- [crossrefapi](https://github.com/fabiobatalha/crossrefapi) (Python)
+
+If you know of another library you would like to see listed here, please let us know about it via the [issue tracker](https://github.com/CrossRef/rest-api-doc/issues).
+
+### Etiquette
+
+We want to provide a public, open,  and free API for all. And we don't want to unnecessarily burden developers (or ourselves) with cumbersome API tokens or registration processes in order to use the public REST API. For that to work, we ask that you be polite and try not to do anything that will take the public REST API down or otherwise make it unusable for others. Specifically, we encourage the following polite behaviour:
+
+- Cache data so you don't request the same data over and over again. 
+- Actively monitor API response times. If they start to go up, back-off for a while. For example, add pauses between requests and/or reduce the number of parallel requests.
+- Specify a `User-Agent` header that properly identifies your script or tool and that provides some type of means of contacting you. For example:
+`GroovyBib/1.1 (https://example.org/GroovyBib/; GroovyBib@example.org) BasedOnFunkyLib/1.4`.
+
+This way we can contact you if we see a problem.
+
+- report problems and/or ask questions on our [issue tracker](https://github.com/CrossRef/rest-api-doc/issues).
+
+Alas, not all people are polite. And for this reason we reserve the right to impose rate limits and/or to block clients that are disrupting the public service.
+
+#### Rate limits
 
 From time to time Crossref needs to impose rate limits to ensure that the free API is usable by all. Any rate limits that are in effect will be advertised in the `X-Rate-Limit-Limit` and `X-Rate-Limit-Interval` HTTP headers.
 
-## Overview
+#### Blocking
+
+This is always our last resort, and you can generally avoid it if you include contact information in the `User-Agent` header as described above.
+
+But seriously... this is a bummer. We really want you to use the API. If you are polite about it, you shouldn't have any problems.
+
+### Use for production services
+
+What if you want to use our API for a production service that cannot depend on the performance uncertainties of the free and open public API? What if you don't want to be affected by impolite people who do not follow the [API Etiquette](#api-etiquette) guidelines? Well, if you’re interested in using these tools or APIs for production services, we’ll soon have a service-level offering with access to all supported APIs and metadata, but with extra service and support guarantees. If you are interested in the upcoming service-based offering please contact our [outreach team](mailto://member@crossref.org). 
+
+## API overview
 
 The API is generally RESTFUL and returns results in JSON. JSON formats returned by the API are documented [here](https://github.com/CrossRef/rest-api-doc/blob/master/api_format.md).
 
@@ -111,7 +144,7 @@ Will return the following result:
 
 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
+## Result types
 
 All results are returned in JSON. There are three general types of results:
 
@@ -125,7 +158,7 @@ The mime-type for API results is `application/vnd.crossref-api-message+json`
 
 Singletons are single results. Retrieving metadata for a specific identifier (e.g. DOI, ISSN, funder_identifier) typically returns in a singleton result.
 
-### Headers Only
+### Headers only
 
 You can use HTTP HEAD requests to quickly determine "existence" of a singleton. The advantage of this technique is that it is very fast because it does not return any metadata- it only retruns headers and an HTTP status code (200=exists, 404=does not exist).
 
@@ -161,12 +194,12 @@ Note that the "message-type" returned will differ from the mime-type:
 
 Normally, an API list result will return both the summary and the items. If you want to just retrieve the summary, you can do so by specifying that the number of rows returned should be zero. 
 
-### Sort order
+#### Sort order
 
 If the API call includes a query, then the sort order will be by the relevance score. If no query is included, then the sort order will be by DOI update date.
 
 
-## Resource Components
+## Resource components
 Major resource components supported by the Crossref API are:
 
 - works
@@ -295,7 +328,7 @@ An example that sorts results in order of publication, beginning with the least
 
     https://api.crossref.org/works?query=josiah+carberry&sort=published&order=asc
 
-## Facet Counts
+## Facet counts
 
 Facet counts can be retrieved by enabling faceting. Facets are enabled by providing facet field names along with a maximum number of returned term values. The larger the number of returned values, the longer the query will take. Some facet fields
 can accept a `*` as their maximum, which indicates that all values should be returned.
@@ -323,7 +356,7 @@ Facets are specified with the `facet` parameter:
 | `relation-type` | `*` | Relation type described by work or described by another work with work as object |
 | `assertion-group` | `*` | Custom Crossmark assertion group name |
 
-## Filter Names
+## Filter names
 
 Filters allow you to narrow queries. All filter results are lists.  The following filters are supported:
 
@@ -459,7 +492,7 @@ The number of returned items is controlled by the `rows` parameter, but you can
 
 Offsets for `/works` are limited to 10K. Use `cursor` (see below) for larger `/works` results sets.
 
-### Deep Paging with Cursors
+### Deep paging with cursors
 
 Using large `offset` values can result in extremely long response times. Offsets in the 100,000s and beyond will likely cause a timeout before the API is able to respond. An alternative to paging through very large result sets (like a corpus used for text and data mining) it to use the API's exposure of Solr's deep paging cursors. Any combination of query, filters and facets may be used with deep paging cursors. While `rows` may be specified along with `cursor`, `offset` and `sample` cannot be used. To use deep paging make a query as normal, but include the `cursor` parameter with a value of `*`. In this example we will page through all `journal-article` works from member `311`:
 
@@ -482,7 +515,7 @@ Being able to select random results is useful for both testing and sampling. You
 Note that when you use the `sample` parameter, the `rows` and `offset` parameters are ignored.
 
 
-### Example Queries
+### Example queries
 
 **All works published by owner prefix `10.1016` in January 2010**
 
@@ -547,3 +580,57 @@ If you need to tie your implementation to a specific major version of the API, y
     https://api.crossref.orv/v1/works
     
 Each major version has no backwards incompatible changes within its public interface.
+
+## Documentation history
+
+- V1: 2013-09-08, first draft.
+- V2: 2013-09-24, reference platform deployed
+- v3: 2013-09-25, reworked filters. Added API versioning doc 
+- v4: 2013-09-25, more filter changes.
+- v5: 2013-09-27, doc mime-type and message-type relationship
+- v6: 2013-10-01, updated `sample` & added examples with filters
+- v6: 2013-10-01, corrected warning date
+- v7: 2013-10-02, fixed typos
+- v8: 2013-10-17, updated warning. Added email address
+- v9: 2013-12-13, update example urls
+- v10: 2013-12-13, /types routes, type filter, issn filter
+- v11: 2013-12-14, indexed timestamps, has-archive and archive implemented
+- v12: 2014-01-06, directory filter
+- v13: 2014-02-10, new `/members`, `/publishers` becomes `/prefixes`, new `member` filter, `publisher` filter becomes `prefix`
+- v14: 2014-02-14, new `has-funder` filter.
+- v15: 2014-02-27, new `/licenses` route
+- v16: 2014-05-19, new `/journals` route, new CrossMark (updates and update policy) filters, new `sort` and `order` parameters
+- v17: 2014-05-19, new `facet` query parameter
+- v18: 2014-05-29, new `/works/{doi}/agency` route
+- v19: 2014-06-23, new textual filters - `container-title`, `category-name`.
+- v20: 2014-06-24, OR filter queries, `type-name` filter.
+- 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.
+- 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
+- v28, 2016-05-09, added link to source of category lables
+- v29, 2016-05-24, added field queries
+- v30, 2016-09-26, highlight issue tracker
+- v31, 2016-10-05, document `has-clinical-trial-number` and `has-abstract` filters
+- v32, 2016-10-27, document rate limit headers
+- v33, 2016-11-07, guidance on when to use `offset` vs `cursor`
+- v34, 2017-04-26, document support for HTTPS. Update examples to use HTTPS.
+- v35, 2017-04-26, document use of head reqeusts to determine `existence`
+- v36, 2017-04-27, fixed license route examples to use facet/filter instead
+- v37, 2017-04-27, `query.bibliographic`
+- v38, 2017-04-27, add v1.1 filters and sort fields
+- v39, 2017-04-27, remove mention of dismax
+- v40, 2017-04-27, clarify faceting feature
+- v41, 2017-04-28, document `sample` max = 100, clarify cursors only work on some routes
+- v42, 2017-04-28, life, the universe, and everything
+- v43, 2017-04-28, reminder on the wisdom of url-encoding
+- v44, 2017-04-28, clarify that field queries apply to `/works` route
+- v45, 2017-04-28, document `location` filter for `/funders` route
+- v46, 2017-06-14, minor text changes and new funder registry link
+- v47, 2017-07-04, clarify `query.affiliation`
+- v48, 2017-07-13, correct "first and given" names to "given and family"
+- v49, 2017-07-20, move document version history, add section on libraries
+- v50, 2017-07-20, add TOC, move document history, add etiquet section, add production use section, general formatting + cleanup

From 9e1fa4f74472f2f17ecd3465044c767fd86bc9e7 Mon Sep 17 00:00:00 2001
From: Geoffrey Bilder 
Date: Thu, 20 Jul 2017 11:27:17 +0200
Subject: [PATCH 161/219] document version history

---
 rest_api.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/rest_api.md b/rest_api.md
index 05f626e..0763e09 100644
--- a/rest_api.md
+++ b/rest_api.md
@@ -19,7 +19,7 @@
 - [Facet counts](#facet-counts)
 - [Filter names](#filter-names)
 - [Result controls](#result-controls)
-- [Versioning](#versioning)
+- [API versioning](#api-versioning)
 - [Documentation history](#documentation-history)
 
 
@@ -555,7 +555,7 @@ Note that the filters for license URL and maximum license embargo period (licens
 
     https://api.crossref.org/works?filter=award.number:1F31MH11745,award.funder:10.13039/100000025
 
-## Versioning
+## API versioning
 
 In theory, the syntax of the API can vary independently of the result representations. In practice, major version changes in either will require changes to API clients and so versioning of the API will apply to both the API syntax and the result representation.
 

From 19c556e4d9e60c0200d398e72a1b2b96ea2dc7c4 Mon Sep 17 00:00:00 2001
From: Geoffrey Bilder 
Date: Thu, 20 Jul 2017 11:32:11 +0200
Subject: [PATCH 162/219] punctuation

---
 rest_api.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/rest_api.md b/rest_api.md
index 0763e09..d397469 100644
--- a/rest_api.md
+++ b/rest_api.md
@@ -50,7 +50,7 @@ Note that we generally post notice any ongoing performance problems with our ser
 
 ### Reporting performance or avialability problems
 
-Report performance/avialability at our [support site](https://support.crossref.org/hc/en-us)
+Report performance/avialability at our [support site](https://support.crossref.org/hc/en-us).
 
 ### Reporting bugs, requesting features ###
 

From fbfb381917df5820e5743e2fa6fd187721571d57 Mon Sep 17 00:00:00 2001
From: kmeddings 
Date: Thu, 20 Jul 2017 10:41:09 +0100
Subject: [PATCH 163/219] Update rest_api.md

Minor text changes
---
 rest_api.md | 12 ++++++------
 1 file changed, 6 insertions(+), 6 deletions(-)

diff --git a/rest_api.md b/rest_api.md
index d397469..a087695 100644
--- a/rest_api.md
+++ b/rest_api.md
@@ -26,7 +26,7 @@
 
 ## Service alert: 18 July 2017
 
- Cited-by counts are not are not updating and should not be considered accurate. We are working on a fix and will update you ([see below](#learning-about-performanceavialability-problems)) when it is in place.
+ Cited-by counts are not are not updating and should not be considered accurate. We are working on a fix and will update you ([see below](#learning-about-performanceavailability-problems)) when it is in place.
 
 ## What's new: July 2017
 
@@ -44,13 +44,13 @@ The Crossref REST API is one of [a variety of tools and APIs](https://www.crossr
 
 
 ## Meta
-### Learning about performance or avialability problems
+### Learning about performance or availability problems
 
 Note that we generally post notice any ongoing performance problems with our services on our twitter feeds at [CrossRefOrg](https://twitter.com/CrossrefOrg) and [CrossRefSupport](https://twitter.com/@CrossrefSupport). We also report them on our [support site](https://support.crossref.org/hc/en-us). You might want to check these to see if we are already aware of a problem before you report it.
 
-### Reporting performance or avialability problems
+### Reporting performance or availability problems
 
-Report performance/avialability at our [support site](https://support.crossref.org/hc/en-us).
+Report performance/availability at our [support site](https://support.crossref.org/hc/en-us).
 
 ### Reporting bugs, requesting features ###
 
@@ -567,9 +567,9 @@ The API uses a semantic versioning scheme whereby the version number is divided
         major  |
            minor
 
- **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 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, and Crossref will only maintain the latest minor version for the two most recent major versions.
+**Minor** version increments are defined as backwards compatible. There is no limit on the number of minor versions that Crossref can roll out. Note that client applications should not have dependencies on minor versions, and Crossref will only maintain the latest minor version for the two most recent major versions.
 
 Adding syntax options or metadata to representations will normally be backwards compatible and will thus normally only trigger minor version changes. Renaming or restructuring syntax options of metadata tends not to be backward compatible and will thus typically trigger major version changes
 

From 63c5daf82f36b44c4a7dfde3960dee9fa52b6fd0 Mon Sep 17 00:00:00 2001
From: mwats0n 
Date: Thu, 20 Jul 2017 11:04:54 +0100
Subject: [PATCH 164/219] Removed repeated text

---
 rest_api.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/rest_api.md b/rest_api.md
index a087695..f88ba23 100644
--- a/rest_api.md
+++ b/rest_api.md
@@ -26,7 +26,7 @@
 
 ## Service alert: 18 July 2017
 
- Cited-by counts are not are not updating and should not be considered accurate. We are working on a fix and will update you ([see below](#learning-about-performanceavailability-problems)) when it is in place.
+ Cited-by counts are not updating and should not be considered accurate. We are working on a fix and will update you ([see below](#learning-about-performanceavailability-problems)) when it is in place.
 
 ## What's new: July 2017
 

From c67ffb7e52e6d42a5754f113a09704679f93d526 Mon Sep 17 00:00:00 2001
From: Geoffrey Bilder 
Date: Thu, 20 Jul 2017 14:24:02 +0200
Subject: [PATCH 165/219] deprecate old files, move main documentation to
 README.md

---
 README.md                                     | 644 +++++++++++++++++-
 .../ad_hoc_deposits.md                        |   0
 .../archive_query_api.md                      |   0
 deposit_api.md => deprecated/deposit_api.md   |   0
 .../resource_intended_use_hints.md            |   0
 .../rest_api_koans.md                         |   0
 .../rest_api_tour.md                          |   0
 scratch.md => deprecated/scratch.md           |   0
 labs_email.png                                | Bin 7932 -> 0 bytes
 rest_api.md                                   | 634 +----------------
 10 files changed, 629 insertions(+), 649 deletions(-)
 rename ad_hoc_deposits.md => deprecated/ad_hoc_deposits.md (100%)
 rename archive_query_api.md => deprecated/archive_query_api.md (100%)
 rename deposit_api.md => deprecated/deposit_api.md (100%)
 rename resource_intended_use_hints.md => deprecated/resource_intended_use_hints.md (100%)
 rename rest_api_koans.md => deprecated/rest_api_koans.md (100%)
 rename rest_api_tour.md => deprecated/rest_api_tour.md (100%)
 rename scratch.md => deprecated/scratch.md (100%)
 delete mode 100644 labs_email.png

diff --git a/README.md b/README.md
index 9eeb07f..f88ba23 100644
--- a/README.md
+++ b/README.md
@@ -1,24 +1,636 @@
-# rest-api-doc
+# Crossref REST API
 
-Documentation for CrossRef's REST API.
+
+
 
-## How to us this repository
+
 
-This is a simple documentation repo. The following files can help you navigate CrossRef's API:
+- [Service alert: 18 July 2017](#service-alert-18-july-2017)
+- [What's new: July 2017](#whats-new-july-2017)
+- [Preamble](#preamble)
+- [Meta](#meta)
+- [API overview](#api-overview)
+- [Result types](#result-types)
+- [Resource components](#resource-components)
+- [Parameters](#parameters)
+- [Queries](#queries)
+- [Field Queries](#field-queries)
+- [Sorting](#sorting)
+- [Facet counts](#facet-counts)
+- [Filter names](#filter-names)
+- [Result controls](#result-controls)
+- [API versioning](#api-versioning)
+- [Documentation history](#documentation-history)
 
- * [rest_api.md](rest_api.md) CrossRef REST API. This is the main file. 
- * [rest_api_koans.md](rest_api_koans.md) - CrossRef API Koans. These are basic questions with their answers about how to use the API.
- * [rest_api_tour.md](rest_api_tour.md) - These short examples show how the CrossRef REST APIs can be used to provide CrossPublisher suport for TDM applications. This demonstration is a bit of a paradox- it is targeted at a  non-technical audience who wants to understand a little but about the technical infrastructure that researchers can leverage for TDM applications.
- * [ad_hoc_deposits.md](ad_hoc_deposits.md) - A Guide to Making Ad hoc XML Deposits Using CrossRef's Manual XML Deposit Interface
- * [archive_query_api.md](archive_query_api.md) - Archive Arrangement Query API
- * [deposit_api.md](deposit_api.md) - CrossRef RESTful Deposit API
- * [resource_intended_use_hints.md](resource_intended_use_hints.md) - Resource Intended Use Hints Through CrossRef Metadata
- * [scratch.md](scratch.md) - Content "Syndication" through CrossRef Metadata
+
 
-Example XML queries can be found in the example/ folder.
+## Service alert: 18 July 2017
 
-### Key Perfomance Indicators
+ Cited-by counts are not updating and should not be considered accurate. We are working on a fix and will update you ([see below](#learning-about-performanceavailability-problems)) when it is in place.
 
-This documentation has moved. Please [click here](http://api.crossref.org) to get to the new location. The canonical URL for this documentation is http://api.crossref.org . Please update your bookmarks.
+## What's new: July 2017
 
-CrossRef metadata best practice to support key performance indicators (KPIs) for funding agencies is still available at [funder_kpi_metadata_best_practice.md](funder_kpi_metadata_best_practice.md).
\ No newline at end of file
+- References are now included if the publisher has made them public.
+- Metadata for preprints, listed as "posted-content"
+- Links from preprints to subsequent publications using "isPreprintOf" relationship
+- Abstracts for over 1 million DOIs
+- Subject categories have been updated to cover more of the content (~45,000 journal titles)
+- "is-referenced-by-count" - also known as cited-by counts.
+
+
+## Preamble
+
+The Crossref REST API is one of [a variety of tools and APIs](https://www.crossref.org/services/metadata-delivery/) that allow anybody to search and reuse our members' metadata in sophisticated ways.
+
+
+## Meta
+### Learning about performance or availability problems
+
+Note that we generally post notice any ongoing performance problems with our services on our twitter feeds at [CrossRefOrg](https://twitter.com/CrossrefOrg) and [CrossRefSupport](https://twitter.com/@CrossrefSupport). We also report them on our [support site](https://support.crossref.org/hc/en-us). You might want to check these to see if we are already aware of a problem before you report it.
+
+### Reporting performance or availability problems
+
+Report performance/availability at our [support site](https://support.crossref.org/hc/en-us).
+
+### Reporting bugs, requesting features ###
+
+Please report bugs with the API or the documentation on our [issue tracker](https://github.com/CrossRef/rest-api-doc/issues).
+
+### 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.
+
+### Privacy
+
+We also have a [privacy policy](https://www.crossref.org/privacy/).
+
+### Libraries
+
+You might be able to avoid reading all this documentation if you instead use one of the several excellent libraries that have been written for the Crossref REST API. For example:
+
+- [habanero](https://github.com/sckott/habanero) (Python)
+- [serrano](https://github.com/sckott/serrano) (Ruby)
+- [rcrossref](https://github.com/ropensci/rcrossref) (R)
+- [crossrefapi](https://github.com/fabiobatalha/crossrefapi) (Python)
+
+If you know of another library you would like to see listed here, please let us know about it via the [issue tracker](https://github.com/CrossRef/rest-api-doc/issues).
+
+### Etiquette
+
+We want to provide a public, open,  and free API for all. And we don't want to unnecessarily burden developers (or ourselves) with cumbersome API tokens or registration processes in order to use the public REST API. For that to work, we ask that you be polite and try not to do anything that will take the public REST API down or otherwise make it unusable for others. Specifically, we encourage the following polite behaviour:
+
+- Cache data so you don't request the same data over and over again. 
+- Actively monitor API response times. If they start to go up, back-off for a while. For example, add pauses between requests and/or reduce the number of parallel requests.
+- Specify a `User-Agent` header that properly identifies your script or tool and that provides some type of means of contacting you. For example:
+`GroovyBib/1.1 (https://example.org/GroovyBib/; GroovyBib@example.org) BasedOnFunkyLib/1.4`.
+
+This way we can contact you if we see a problem.
+
+- report problems and/or ask questions on our [issue tracker](https://github.com/CrossRef/rest-api-doc/issues).
+
+Alas, not all people are polite. And for this reason we reserve the right to impose rate limits and/or to block clients that are disrupting the public service.
+
+#### Rate limits
+
+From time to time Crossref needs to impose rate limits to ensure that the free API is usable by all. Any rate limits that are in effect will be advertised in the `X-Rate-Limit-Limit` and `X-Rate-Limit-Interval` HTTP headers.
+
+#### Blocking
+
+This is always our last resort, and you can generally avoid it if you include contact information in the `User-Agent` header as described above.
+
+But seriously... this is a bummer. We really want you to use the API. If you are polite about it, you shouldn't have any problems.
+
+### Use for production services
+
+What if you want to use our API for a production service that cannot depend on the performance uncertainties of the free and open public API? What if you don't want to be affected by impolite people who do not follow the [API Etiquette](#api-etiquette) guidelines? Well, if you’re interested in using these tools or APIs for production services, we’ll soon have a service-level offering with access to all supported APIs and metadata, but with extra service and support guarantees. If you are interested in the upcoming service-based offering please contact our [outreach team](mailto://member@crossref.org). 
+
+## API overview
+
+The API is generally RESTFUL and returns results in JSON. JSON formats returned by the API are documented [here](https://github.com/CrossRef/rest-api-doc/blob/master/api_format.md).
+
+The API supports HTTP and HTTPS. Examples here are provided using HTTPS.
+
+You should always url-encode DOIs and parameter values when using the API. DOIs are notorious for including characters that break URLs (e.g. semicolons, hashes, slashes, ampersands, question marks, etc.).
+
+Note that, for the sake of clarity, the examples in this document do *not* url-encode DOIs or parameter values. 
+
+The API will only work for Crossref DOIs. You can test the registration agency for a DOI using the following route:
+
+`https://api.crossref.org/works/{doi}/agency`
+
+Testing the following Crossref DOI:
+
+`10.1037/0003-066X.59.1.29`
+
+Using the URL:
+
+`https://api.crossref.org/works/10.1037/0003-066X.59.1.29/agency`
+
+Will return the following result:
+
+    {
+      status: "ok",
+      message-type: "work-agency",
+      message-version: "1.0.0",
+      message: {
+        DOI: "10.1037/0003-066x.59.1.29",
+        agency: {
+          id: "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.
+
+## Result types
+
+All results are returned in JSON. There are three general types of results:
+
+- Singletons
+- Headers-only
+- Lists
+
+The mime-type for API results is `application/vnd.crossref-api-message+json` 
+
+### Singletons
+
+Singletons are single results. Retrieving metadata for a specific identifier (e.g. DOI, ISSN, funder_identifier) typically returns in a singleton result.
+
+### Headers only
+
+You can use HTTP HEAD requests to quickly determine "existence" of a singleton. The advantage of this technique is that it is very fast because it does not return any metadata- it only retruns headers and an HTTP status code (200=exists, 404=does not exist).
+
+To determine if member ID `98` exists:
+
+`curl --head "http://api.crossref.org/members/98"`
+
+To determine if a journal with ISSN `1549-7712` exists:
+
+`curl --head "http://api.crossref.org/journals/1549-7712"`
+
+### Lists
+Lists results can contain multiple entries. Searching or filtering typically returns a list result. A list has two parts:
+
+- Summary, which include the following information:
+
+    - status (e.g. "ok", error)
+    - message-type (e.g. "work-list" )
+    - message-version (e.g. 1.0.0 )
+    
+- Items, which will will contain the items matching the query or filter. 
+
+Note that the "message-type" returned will differ from the mime-type:
+
+- funder (singleton)
+- prefix (singleton)
+- member (singleton)
+- work (singleton)
+- work-list (list)
+- funder-list (list)
+- prefix-list (list)
+- member-list (list)
+
+Normally, an API list result will return both the summary and the items. If you want to just retrieve the summary, you can do so by specifying that the number of rows returned should be zero. 
+
+#### Sort order
+
+If the API call includes a query, then the sort order will be by the relevance score. If no query is included, then the sort order will be by DOI update date.
+
+
+## Resource components
+Major resource components supported by the Crossref API are:
+
+- works
+- funders
+- members
+- prefixes
+- types
+- journals
+
+These can be used alone like this
+
+| resource      | description                       |
+|:--------------|:----------------------------------|
+| `/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 [Funder Registry](https://github.com/CrossRef/open-funder-registry
+| `/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 |
+
+
+### 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. |
+| `/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 |
+| `/types/{type_id}` | returns information about a metadata work type |
+| `/journals/{issn}` | returns information about a journal with the given ISSN |
+
+### Combining resource components
+
+The works component can be appended to other resources.
+
+| resource                    | description                       |
+|:----------------------------|:----------------------------------|
+| `/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) |
+| `/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.
+
+| parameter                    | description                 |
+|:-----------------------------|:----------------------------|
+| `query`                      | query terms |
+| `filter={filter_name}:{value}`| filter results by specific fields |
+| `rows={#}`                   | results per per page | 
+| `offset={#}` (mak 10k)               | result offset (user `cursor` for larger `/works` result sets)  |                         
+| `sample={#}` (max 100)                | return random N results |
+| `sort={#}`                   | sort results by a certain field |
+| `order={#}`                  | set the sort order to `asc` or `desc` |
+| `facet={#}`                    | enable facet information in responses |
+| `cursor={#}`		       | deep page through `/works` result sets |
+
+Multiple filters can be specified by separating name:value pairs with a comma:
+
+    https://api.crossref.org/works?filter=has-orcid:true,from-pub-date:2004-04-04
+
+### Example query using URI parameters
+
+    https://api.crossref.org/funders/100000015/works?query=global+state&filter=has-orcid:true&rows=1
+
+## Queries
+
+Free form search queries can be made, for example, works that include `renear` and `ontologies`:
+
+    https://api.crossref.org/works?query=renear+ontologies
+	
+## Field Queries
+
+Field queries are available on the `/works` route and allow for queries that match only particular fields
+of metadata. For example, this query matches records that contain the tokens `richard` or `feynman` (or both)
+in any author field:
+
+    https://api.crossref.org/works?query.author=richard+feynman
+	
+Field queries can be combined with the general `query` paramter and each other. Each query parameter
+is ANDed with the others:
+
+    https://api.crossref.org/works?query.title=room+at+the+bottom&query.author=richard+feynman
+	
+### `/works` Field Queries
+
+These field queries are available on the `/works` route:
+
+| Field query parameter | Description |
+|-----------------------|-------------|
+| `query.title` | Query `title` and `subtitle` |
+| `query.container-title` | Query `container-title` aka. publication name |
+| `query.author` | Query author given and family names |
+| `query.editor` | Query editor given and family names |
+| `query.chair` | Query chair given and family names |
+| `query.translator` | Query translator given and family names |
+| `query.contributor` | Query author, editor, chair and translator given and family names |
+| `query.bibliographic` | Query bibliographic infomration, useful for citation look up. Includes titles, authors, ISSNs and publication years |
+| `query.affiliation` | Query contributor affiliations |
+
+## Sorting
+
+Results from a listy response can be sorted by applying the `sort` and `order` parameters. Order
+sets the result ordering, either `asc` or `desc`. Sort sets the field by which results will be
+sorted. Possible values are:
+
+| Sort value | Description |
+|------------|-------------|
+| `score` or `relevance` | Sort by relevance score |
+| `updated` | Sort by date of most recent change to metadata. Currently the same as `deposited`. |
+| `deposited` | Sort by time of most recent deposit |
+| `indexed` | Sort by time of most recent index |
+| `published` | Sort by publication date |
+| `published-print` | Sort by print publication date |
+| `published-online` | Sort by online publication date |
+| `issued` | Sort by issued date (earliest known publication date) |
+| `is-referenced-by-count` | Sort by number of references to documents |
+| `references-count` | Sort by number of references made by documents |
+
+An example that sorts results in order of publication, beginning with the least recent:
+
+    https://api.crossref.org/works?query=josiah+carberry&sort=published&order=asc
+
+## Facet counts
+
+Facet counts can be retrieved by enabling faceting. Facets are enabled by providing facet field names along with a maximum number of returned term values. The larger the number of returned values, the longer the query will take. Some facet fields
+can accept a `*` as their maximum, which indicates that all values should be returned.
+
+Facets are specified with the `facet` parameter:
+
+    https://api.crossref.org/works?rows=0&facet=type-name:*
+    
+| Facet name | Maximum values | Description |
+|:-----------|:---------------|-------------|
+| `affiliation` | `*` | Author affiliation | 
+| `year` | `*` | Earliest year of publication, synonym for `published` |
+| `funder-name` | `*` | Funder literal name as deposited alongside DOIs |
+| `funder-doi` | `*` | Funder DOI |
+| `orcid` | 100 | Contributor ORCID | 
+| `container-title` | 100 | Work container title, such as journal title, or book title |
+| `assertion` | `*` | Custom Crossmark assertion name |
+| `archive` | `*` | Archive location |
+| `update-type` | `*` | Significant update type |
+| `issn` | 100 | Journal ISSN (any - print, electronic, link) |
+| `published` | `*` | Earliest year of publication |
+| `type-name` | `*` | Work type name, such as `journal-article` or `book-chapter` |
+| `license` | `*` | License URI of work |
+| `category-name` | `*` | Category name of work |
+| `relation-type` | `*` | Relation type described by work or described by another work with work as object |
+| `assertion-group` | `*` | Custom Crossmark assertion group name |
+
+## Filter names
+
+Filters allow you to narrow queries. All filter results are lists.  The following filters are supported:
+
+| filter     | possible values | description|
+|:-----------|:----------------|:-----------|
+| `has-funder` | | metadata which includes one or more funder entry |
+| `funder` | `{funder_id}` | metadata which include the `{funder_id}` in FundRef data |
+| `location` |`{country_name}` | funder records where location = `{country name}`. Only works on `/funders` route |
+| `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 |
+| `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}` |
+| `until-deposit-date` | `{date}` | metadata last (re)deposited before (inclusive) `{date}` |
+| `from-update-date` | `{date}` | Metadata updated since (inclusive) `{date}`. Currently the same as `from-deposit-date`. |
+| `until-update-date` | `{date}` | Metadata updated before (inclusive) `{date}`. Currently the same as `until-deposit-date`. |
+| `from-created-date` | `{date}` | metadata first deposited since (inclusive) `{date}` |
+| `until-created-date` | `{date}` | metadata first deposited before (inclusive) `{date}` |
+| `from-pub-date` | `{date}` | metadata where published date is since (inclusive) `{date}` |
+| `until-pub-date` | `{date}` | metadata where published date is before (inclusive)  `{date}` |
+| `from-online-pub-date` | `{date}` | metadata where online published date is since (inclusive) `{date}` |
+| `until-online-pub-date` | `{date}` | metadata where online published date is before (inclusive)  `{date}` |
+| `from-print-pub-date` | `{date}` | metadata where print published date is since (inclusive) `{date}` |
+| `until-print-pub-date` | `{date}` | metadata where print published date is before (inclusive)  `{date}` |
+| `from-posted-date` | `{date}` | metadata where posted date is since (inclusive) `{date}` |
+| `until-posted-date` | `{date}` | metadata where posted date is before (inclusive)  `{date}` |
+| `from-accepted-date` | `{date}` | metadata where accepted date is since (inclusive) `{date}` |
+| `until-accepted-date` | `{date}` | metadata where accepted date is before (inclusive)  `{date}` |
+| `has-license` | | metadata that includes any `` elements. |
+| `license.url` | `{url}` | metadata where `` value equals `{url}` |
+| `license.version` | `{string}` | metadata where the ``'s `applies_to` attribute  is `{string}`|
+| `license.delay` | `{integer}` | metadata where difference between publication date and the ``'s `start_date` attribute is <= `{integer}` (in days)|
+| `has-full-text` |  | metadata that includes any full text `` elements. |
+| `full-text.version` | `{string}`  | metadata where `` element's `content_version` attribute is `{string}`. |
+| `full-text.type` | `{mime_type}`  | metadata where `` element's `content_type` attribute is `{mime_type}` (e.g. `application/pdf`). |
+| `has-references` | | metadata for works that have a list of references |
+| `has-archive` | | metadata which include name of archive partner |
+| `archive` | `{string}` | metadata which where value of archive partner is `{string}` |
+| `has-orcid` | | metadata which includes one or more ORCIDs |
+| `has-authenticated-orcid` | | metadata which includes one or more ORCIDs where the depositing publisher claims to have witness the ORCID owner authenticate with ORCID |
+| `orcid` | `{orcid}` | metadata where `` element's value = `{orcid}` |
+| `issn` | `{issn}` | metadata where record has an ISSN = `{issn}`. Format is `xxxx-xxxx`. |
+| `type` | `{type}` | metadata records whose type = `{type}`. Type must be an ID value from the list of types returned by the `/types` resource |
+| `directory` | `{directory}` | metadata records whose article or serial are mentioned in the given `{directory}`. Currently the only supported value is `doaj`. |
+| `doi` | `{doi}` | metadata describing the DOI `{doi}` |
+| `updates` | `{doi}` | metadata for records that represent editorial updates to the DOI `{doi}` |
+| `is-update` | | metadata for records that represent editorial updates |
+| `has-update-policy` | | metadata for records that include a link to an editorial update policy |
+| `container-title` | | metadata for records with a publication title exactly with an exact match |
+| `category-name` | | metadata for records with an exact matching category label. Category labels come from [this list](https://www.elsevier.com/solutions/scopus/content) published by Scopus |
+| `type` | | metadata for records with type matching a type identifier (e.g. `journal-article`) |
+| `type-name` | | metadata for records with an exacty matching type label |
+| `award.number` | `{award_number}` | metadata for records with a matching award nunber. Optionally combine with `award.funder` |
+| `award.funder` | `{funder doi or id}` | metadata for records with an award with matching funder. Optionally combine with `award.number` |
+| `has-assertion` | | metadata for records with any assertions |
+| `assertion-group` | | metadata for records with an assertion in a particular group |
+| `assertion` | | metadata for records with a particular named assertion |
+| `has-affiliation` | | metadata for records that have any affiliation information |
+| `alternative-id` | | metadata for records with the given alternative ID, which may be a publisher-specific ID, or any other identifier a publisher may have provided |
+| `article-number` | | metadata for records with a given article number |
+| `has-abstract` | | metadata for records which include an abstract |
+| `has-clinical-trial-number` | | metadata for records which include a clinical trial number |
+| `content-domain` | | metadata where the publisher records a particular domain name as the location Crossmark content will appear |
+| `has-content-domain` | | metadata where the publisher records a domain name location for Crossmark content |
+| `has-crossmark-restriction` | | metadata where the publisher restricts Crossmark usage to content domains |
+| `has-relation` | | metadata for records that either assert or are the object of a relation |
+| `relation.type` | | One of the relation types from the Crossref relations schema (e.g. `is-referenced-by`, `is-parent-of`, `is-preprint-of`) |
+| `relation.object` | | Relations where the object identifier matches the identifier provided |
+| `relation.object-type` | | One of the identifier types from the Crossref relations schema (e.g. `doi`, `issn`) |
+
+### Multiple filters
+
+Multiple filters can be specified in a single query. In such a case, different filters will be applied with AND semantics, while specifying the same filter multiple times will result in OR semantics - that is, specifying the filters:
+
+- `is-update:true`
+- `from-pub-date:2014-03-03`
+- `funder:10.13039/100000001`
+- `funder:10.13039/100000050`
+
+would locate documents that are updates, were published on or after 3rd March 2014 and were funded by either the National Science Foundation (`10.13039/100000001`) or the National Heart, Lung, and Blood Institute (`10.13039/100000050`). These filters would be specified by joining each filter together with a comma:
+
+    /works?filter=is-update:true,from-pub-date:2014-03-03,funder:10.13039/100000001,funder:10.13039/100000050
+    
+### Dot filters
+
+A filter with a dot in its name is special. The dot signifies that the filter will be applied to some other record type that is related to primary resource record type. For example, with work queries, one can filter on works that have an award, where the same award has a particular award number and award-gving funding agency:
+
+    /works?filter=award.number:CBET-0756451,award.funder:10.13039/100000001
+    
+Here we filter on works that have an award by the National Science Foundation that also has the award number `CBET-0756451`.
+
+### 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. 
+
+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. 
+
+### Notes on incremental metadata updates
+
+When using time filters to retrieve periodic, incremental metadata updates,
+the `from-index-date` filter should be used over `from-update-date`,
+`from-deposit-date`, `from-first-deposit-date` and `from-pub-date`. The
+timestamp that `from-index-date` filters on is guaranteed to be updated
+every time there is a change to metadata requiring a reindex.
+
+## Result controls
+
+You can control the delivery and selection results using the `rows`, `offset` and `sample` parameters.
+
+ If you are expecting results beyond 10K, then use a `cursor` to deep page through the results. Note that not all routes support cursors.
+
+### Rows 
+
+Normally, results are returned 20 at a time. You can control the number of results returns by using the `rows` parameter. To limit results to 5, for example, you could do the following:
+
+    https://api.crossref.org/works?query=allen+renear&rows=5
+
+If you would just like to get the `summary` of the results, you can set the rows to 0 (zero).
+
+    https://api.crossref.org/works?query=allen+renear&rows=0
+    
+The maximum number rows you can ask for in one query is `1000`.
+
+### Offset
+
+The number of returned items is controlled by the `rows` parameter, but you can select the offset into the result list by using the `offset` parameter.  So, for example, to select the second set of 5 results (i.e. results 6 through 10), you would do the following:
+
+    https://api.crossref.org/works?query=allen+renear&rows=5&offset=5
+
+Offsets for `/works` are limited to 10K. Use `cursor` (see below) for larger `/works` results sets.
+
+### Deep paging with cursors
+
+Using large `offset` values can result in extremely long response times. Offsets in the 100,000s and beyond will likely cause a timeout before the API is able to respond. An alternative to paging through very large result sets (like a corpus used for text and data mining) it to use the API's exposure of Solr's deep paging cursors. Any combination of query, filters and facets may be used with deep paging cursors. While `rows` may be specified along with `cursor`, `offset` and `sample` cannot be used. To use deep paging make a query as normal, but include the `cursor` parameter with a value of `*`. In this example we will page through all `journal-article` works from member `311`:
+
+    https://api.crossref.org/members/311/works?filter=type:journal-article&cursor=*
+
+A `next-cursor` field will be provided in the JSON response. To get the next page of results, pass the value of `next-cursor` as the `cursor` parameter:
+
+    https://api.crossref.org/members/311/works?filter=type:journal-article&cursor=AoE/CGh0dHA6Ly9keC5kb2kub3JnLzEwLjEwMDIvdGRtX2xpY2Vuc2VfMQ==
+ 
+Clients should check the number of returned items. If the number of returned items is fewer than the number of expected rows then the end of the result set has been reached. Using `next-cursor` beyond this point will result in responses with an empty items list.
+
+The `cursor` parameter is available on all `/works` resources.
+
+### Sample
+
+Being able to select random results is useful for both testing and sampling. You can use the `sample` parameter to retrieve random results. So, for example, the following select 10 random works:
+
+    https://api.crossref.org/works?sample=10
+    
+Note that when you use the `sample` parameter, the `rows` and `offset` parameters are ignored.
+
+
+### Example queries
+
+**All works published by owner prefix `10.1016` in January 2010**
+
+    https://api.crossref.org/prefixes/10.1016/works?filter=from-pub-date:2010-01,until-pub-date:2010-01
+
+**All works funded by `10.13039/100000001` that have a CC-BY license**
+
+    https://api.crossref.org/funders/10.13039/100000001/works?filter=license.url:http://creativecommons.org/licenses/by/3.0/
+
+**All works published by owner prefix 10.6064 from February 2010 to February 2013 that have a CC-BY license**
+
+    https://api.crossref.org/prefixes/10.6064/works?filter=license.url:http://creativecommons.org/licenses/by/3.0/,from-pub-date:2010-02,until-pub-date:2013-02
+
+**All works funded by `10.13039/100000015` where license = CC-BY and embargo <= 365 days**
+
+    https://api.crossref.org/funders/10.13039/100000015/works?filter=license.url:http://creativecommons.org/licenses/by/3.0/,license.delay:365
+
+Note that the filters for license URL and maximum license embargo period (license.url and license.delay) combine to filter each document's metadata for a license with both of these properties.
+
+**All works where the archive partner listed = 'CLOCKSS'**
+
+    https://api.crossref.org/works?filter=archive:CLOCKSS
+    
+**All members with `hind` in their name (e.g. Hindawi)**
+
+    https://api.crossref.org/members?query=hind
+    
+**All licenses linked to works published by Elsevier**
+
+    http://api.crossref.org/v1/works?facet=license:*&filter=member:78&rows=0
+    
+**All licenses applied to works published in the journal `Pathology Research International`**
+
+    https://api.crossref.org/works?facet=license:*&filter=issn:2090-8091
+    
+**All works with an award numbered roughly `1 F31 MH11745` also awarded by funder with ID `10.13039/100000025`:
+
+    https://api.crossref.org/works?filter=award.number:1F31MH11745,award.funder:10.13039/100000025
+
+## API versioning
+
+In theory, the syntax of the API can vary independently of the result representations. In practice, major version changes in either will require changes to API clients and so versioning of the API will apply to both the API syntax and the result representation.
+
+The API uses a semantic versioning scheme whereby the version number is divided into three parts delimited by periods. The first number represents the "major" release number. The second represents a "minor" release number.
+      
+    Version 1.20
+            ^  ^
+            |  |
+        major  |
+           minor
+
+ **Major** version increments 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 Crossref can roll out. Note that client applications should not have dependencies on minor versions, and Crossref will only maintain the latest minor version for the two most recent major versions.
+
+Adding syntax options or metadata to representations will normally be backwards compatible and will thus normally only trigger minor version changes. Renaming or restructuring syntax options of metadata tends not to be backward compatible and will thus typically trigger major version changes
+
+### How to manage API versions
+
+If you need to tie your implementation to a specific major version of the API, you can do so by using version-specific routes. The default route redirects to the most recent version of the API. Some older major versions may be available using a version prefix. For example, to access version `v1` of the API:
+
+    https://api.crossref.orv/v1/works
+    
+Each major version has no backwards incompatible changes within its public interface.
+
+## Documentation history
+
+- V1: 2013-09-08, first draft.
+- V2: 2013-09-24, reference platform deployed
+- v3: 2013-09-25, reworked filters. Added API versioning doc 
+- v4: 2013-09-25, more filter changes.
+- v5: 2013-09-27, doc mime-type and message-type relationship
+- v6: 2013-10-01, updated `sample` & added examples with filters
+- v6: 2013-10-01, corrected warning date
+- v7: 2013-10-02, fixed typos
+- v8: 2013-10-17, updated warning. Added email address
+- v9: 2013-12-13, update example urls
+- v10: 2013-12-13, /types routes, type filter, issn filter
+- v11: 2013-12-14, indexed timestamps, has-archive and archive implemented
+- v12: 2014-01-06, directory filter
+- v13: 2014-02-10, new `/members`, `/publishers` becomes `/prefixes`, new `member` filter, `publisher` filter becomes `prefix`
+- v14: 2014-02-14, new `has-funder` filter.
+- v15: 2014-02-27, new `/licenses` route
+- v16: 2014-05-19, new `/journals` route, new CrossMark (updates and update policy) filters, new `sort` and `order` parameters
+- v17: 2014-05-19, new `facet` query parameter
+- v18: 2014-05-29, new `/works/{doi}/agency` route
+- v19: 2014-06-23, new textual filters - `container-title`, `category-name`.
+- v20: 2014-06-24, OR filter queries, `type-name` filter.
+- 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.
+- 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
+- v28, 2016-05-09, added link to source of category lables
+- v29, 2016-05-24, added field queries
+- v30, 2016-09-26, highlight issue tracker
+- v31, 2016-10-05, document `has-clinical-trial-number` and `has-abstract` filters
+- v32, 2016-10-27, document rate limit headers
+- v33, 2016-11-07, guidance on when to use `offset` vs `cursor`
+- v34, 2017-04-26, document support for HTTPS. Update examples to use HTTPS.
+- v35, 2017-04-26, document use of head reqeusts to determine `existence`
+- v36, 2017-04-27, fixed license route examples to use facet/filter instead
+- v37, 2017-04-27, `query.bibliographic`
+- v38, 2017-04-27, add v1.1 filters and sort fields
+- v39, 2017-04-27, remove mention of dismax
+- v40, 2017-04-27, clarify faceting feature
+- v41, 2017-04-28, document `sample` max = 100, clarify cursors only work on some routes
+- v42, 2017-04-28, life, the universe, and everything
+- v43, 2017-04-28, reminder on the wisdom of url-encoding
+- v44, 2017-04-28, clarify that field queries apply to `/works` route
+- v45, 2017-04-28, document `location` filter for `/funders` route
+- v46, 2017-06-14, minor text changes and new funder registry link
+- v47, 2017-07-04, clarify `query.affiliation`
+- v48, 2017-07-13, correct "first and given" names to "given and family"
+- v49, 2017-07-20, move document version history, add section on libraries
+- v50, 2017-07-20, add TOC, move document history, add etiquet section, add production use section, general formatting + cleanup
diff --git a/ad_hoc_deposits.md b/deprecated/ad_hoc_deposits.md
similarity index 100%
rename from ad_hoc_deposits.md
rename to deprecated/ad_hoc_deposits.md
diff --git a/archive_query_api.md b/deprecated/archive_query_api.md
similarity index 100%
rename from archive_query_api.md
rename to deprecated/archive_query_api.md
diff --git a/deposit_api.md b/deprecated/deposit_api.md
similarity index 100%
rename from deposit_api.md
rename to deprecated/deposit_api.md
diff --git a/resource_intended_use_hints.md b/deprecated/resource_intended_use_hints.md
similarity index 100%
rename from resource_intended_use_hints.md
rename to deprecated/resource_intended_use_hints.md
diff --git a/rest_api_koans.md b/deprecated/rest_api_koans.md
similarity index 100%
rename from rest_api_koans.md
rename to deprecated/rest_api_koans.md
diff --git a/rest_api_tour.md b/deprecated/rest_api_tour.md
similarity index 100%
rename from rest_api_tour.md
rename to deprecated/rest_api_tour.md
diff --git a/scratch.md b/deprecated/scratch.md
similarity index 100%
rename from scratch.md
rename to deprecated/scratch.md
diff --git a/labs_email.png b/labs_email.png
deleted file mode 100644
index 0da924e2da35ca0761e28ff65d2bdc16e0653969..0000000000000000000000000000000000000000
GIT binary patch
literal 0
HcmV?d00001

literal 7932
zcmb_=WmH_twsqr92p&R$1PR($AdS1bg~r`!+}+)!aStvbjcafXP6!?>I0X0bNY1(E
zo_Fs1zW3+#7`ykbx#n7{YObmpyLPyuyaX0H2|54(z><;_RerqhJYMvu@Q?pc
zrwAVsMB^fgB#!@-PTg4b6P!dSrI8puMqq&9EZPZlG5}p{hLhKahG-K$Nd?yXjO_t&=q#Cz
zErgYgFb^%if^xm5+WMmSJ44H0DwJj;j|4pWtd%1>szq@*oqDw(3NcSRmHL}mfftHN
zo2pbgVDs|z)YMg`EPw?+O>bn2CeJ#YO$`6pVfYC=05z!x)arm8c?~kp2DlZOZA2i3
zOBohDolUja+#WE!IfkiR8?rJab<3@Wxyg>5)ndl55cyTxrij5&gKg5x;}0rH4-UXz
zzMEfn%&oliQMurQywI25N`bPj)J7I;Q|EK)yqJA`F&
zK#-p#4nhh7vn0HQAmT?M{;!Wyko7B^OQ5A4VA|hf98o@i(+*i1@!cmZI}A)e2|@Ib
zP8k-sWq%9QfFC#n`9fuJgoRJigumcC*F<#}5mJ1MkI*X;9*2`4cs)*2LQEf6mM5af
zclOGOq#0Ew@Fo{!oSXys9?m=HX)64b0oGSQz2Dpi9#T|^uHkQ@ZUmVqM4uK`r5g$P
zu^YOGR-gX>Fb3;&C87!rpdw6&YoIu_l7eyMH;jf0xoErPcx#K
zderq}^|d}gYY@H~?DLRf_kVh}Mr!BNNUY5Uc~gbh@MJcs#c!`0YnA5Mt(ATm|0v)|
zr{fPpFN$__UsB(fE3ssK9kg+1nut~bPbgBzsjR6~aY#_NQ164Dc5x{Amnb+dQF3`AWbSJJSPv5ZW44CbQgKAj8y`e)+kGD&eBw96ZMw%21+EdLrub+{L1Q#jgD9eNeO^|1xcY75avTrGe#~m9aHj1Z{z^uh3)S%s<;wr2l1JnTORVy9k@hjz2
z<`i~FbZGeweHtg9*N+s+=q$;L$m=l3HYiv%dQ}!*K0#lgS-{ix)~Mb-;+TJ3i{?Xk
zmQ;dN^q`!|*XdMm96gR&N1^qkt(lT4UdaNF
z(v4z`7GPi!{UDlVB6gUtUu`6Hh-Wrtj?#0p%bQkPNM6_6yBU$2joxzUvFTa*$~Sl4
zc+2oa=1IInWPeg|;ugsmhHeV||%!z0V1Vt#J^aQ3JuQ;41Cs+1kiM@aUZz>~_wq4aWcNhWlCe+_;8keOXO1-3u$P`6n+JXRH_
z*9o?#fBBs3#R|?tI9^xjrfk)jUX$x4;%s6|=xxGQAH!DkvCfsrT|6Q*=wr}?D6~f>
z+(@cQia=@|UO}ktoAXD#6aS6Uq`0I4I`-0u($5w_wO6%M!qf&49~gAl`DojK-5doh
zBF#eTK5T@-yVF^Ua|Zc4hFFD(!_Pc~_mz=GF7|y;vJ^8_BsJ!{WoyCeK$O
z5zEs`xk?|}_03^N-}{7{gq2p?m`1g*t$VErtPhq-PP&
z_utM%Jn_nR6xj=!t`Of+fR5MtugH$FF?r|QBfQIYXzz0_>c=%BH1obJehIHHLM*2He@C<7C%amnE}di^*Isl3qFnvCko|$=fvM!yD^zn
z^`UBc*dJQ0d)(wuy3lrerv@!Is{-lpcxQRH9faIRe|g!GouaqzW3f|rWYe}|2fI&M
zuZ(F&^4_}9xdkp?G<$ExJY+pbh(x|QWN!C-&|T!)@m{{4Kq-BqD=^~m_TK#7Xn#GQ
z7F~fpyG)?+e&%Y{w6yJPKX+Dt3>Ib<8`3BOd`P~oR_I0=D;;AHuNB{wsFWCsx{g}%
zs5$HXF&qV*S`Y4^`&oaPJW-zG<9gd>W;odM!)jtLO+b3Nq#bng<-%smcza{Y)#9kA
zIAXcHUEsq1KJV7(tUrEdU*Sq2IVW1c)eG(J#Er(r^!v(X(CIB3H`wR#of6GX66^>7
zVBr0_-~j2F!~g)|iiN6%lZKouw~?(4vw^X#p$W5_jol*~0N{1wetfhsaWWuxv$2La
za=Yk_9P6lpF5XV=41o>ASQ4>ca
z2MaqV3tI^Jueb(=w$4s`l$5^`{q_5!pH3F0|IP$){Bu~30|frE09lz?fPck)bmjep
zax0rS+FCpR3a{Z0NS{O@dkc!}8B*g2RuIzGDbzxmVU@7O>28vjni&&Bqq
z!{5PwIw&|;m^=#dt6zWh>F?M-`QZO4!Qa6@9e9DiMEskmzbp1jjep?(o7g697XJ^i
ze_8%h>|ZFiqJ^7@wT7sLjS1wpbZqSGyukm_^0)E*wu{(W+d8P&85o)TlH;GyKiR+Y
zfd8F`<5BW|r}>-V|5_DeqraxQowI}W?}=_~1T?WWc^tBn1^y@d|E!*mOa8B}|F^Z{W?=W9)qG@g%h?)Rn7WG^IGOOX
zv9Pi;v9L0+v8l4MaZLRr#m&@i?lbr2w8{zoF
z_wS7VZ=L?o;Bmv@M}PGE*XG5Kevx$P4FEiGkrEYBb%Q&|Kyg#+#q~?f(3K44Q1%z}
z6Ws0{e;QY$Q3F6%&fcCfbB|CEEkp||87QDv5M?A+!%>YZJ4?VROccZ=kB*bxZ95VG
zf7FF^eSV`Y+~qn7Jz{I&fwA+Lxwx2K=$B6IFiuO%2x3k96(J8*L{wM`PWV~2l)ac%
z#VV=SQd!BQZ+L8C{jW`pck(~-_hwb{V+5^iZ1sx881QH(2#EARAD$S?ME4czpx~9#
zi!uz1jJ);be04#3%7cQ~jED%jz5#1!s!O`XQf$0`uR9Op0rD-?r^o~f#V#9_Gqhw%
z&mW#AZ6J`zn{b3TrYVZ#Jek$jBG0BA?Mz+VojiasE@tD@K~7n*6uEea*n{aeHpZ8
zHCyb!o`Wpj&K9+ddfS-UuU}PHOi~p-PBC;4gjluHmEX!HpS8HUgEbG9OYy3+@9?E!*$#8qISpLjR0e1L6-&f*Zocur|W981Z8lzuzho+^jxHyZ6
zf!;B1z1MU8QE{-nX=7m%C8mCdl%>9fOYD?*oV-oN1={g&NXW`)Nz~I>GxFxk0=J-d
z*VV&fGr3h77uH($p4ry~HMvwl2ub7=t5JAKxaO|Elppi>IAYikPrByvgK+5+_2gi#
zmv$!?tZ{LQFO6knWEea>{W6E4q@8pGf|J~CZp)U=;#6i`Ypt#OJwa;$UR%v@^~}sS
z0nf~A@}@S6s0#2kt?G0;pZt{wCm=gM6D=f%&X#(fPSRc)cgJ*DuUQVrAs?wiib$EtLa
zbL>T8Ib&j?vq_b!A4E)wn_UiNr&|?R--e*3A7#A#ybP-s9FFK9uKUJbp~CTE&n-BX
z_?08in!gG|3OoMISA9&VtDW0uMbdTwm8H{->(2M(563lQTb>-2i)V9N1w@}CSL)A!
z3o|>0zBk7kmwH6sH^K%de7=4&6TT66oi5hYB!J~jni@?6a_`HQTAvHOPpPbRaq4jz
z8s`qidWkz}o4e@NM{PDgCEyk66H&DV4g=dIRGM
zb%OW!9J<9>fdpZ_AV~2&?0-YyeZ%#FKO%eB^C3)=rI?%nBlSS1*gZ1k!Rz4UCm*W}
zAsx!M?ugy8{iea3C7O4-n5-on+NMUpk7YeeJea0m2=VtxE=km1-@t&>;=pX6zV2$f
zg)}d@lpSX%e_A*=?4@ZptNu9FORqw5cB3t=2Wfr>Nn&PHG@b@By&I69*1h7x=+cC(
z_@cXZR&MmI$y5zB#{1PtaB8C5Sg;-!2I95MexvKIXDet<<)saF?HNWUI(6()-XJe^^{kA*Z1yL)
z89Tr(-;<`J+_sT?yfBdhVIxw@7Xu!F5nI}rhS@6<8?(LpJ<&`-3t@A#jgcq@apP-`^P6TYDvA+T-JXn30
zhj8C(VP)29TEj=|wC4nfMDC065q6@i(x%n0E~~g$#ybB#N?0RrgQ&sg>1pT_vfi$x
z=OGhOEA4OWXI&oog3m@dKt&BL%eRZ0nChIIcY{T6cB@-*
z!bX`#q;K!S1GD8rFypGTxmQU@m3dm5>H;0uGPPQy$*-1Xo4T*0vZFI5d-&qV}jp#?)@1E~9RTB?|AqghCK>Vo7x!dJudav62*>o(kc=|PXnG}+&*jsVZ7U;ybRnR60`c;&WwSTlt{+_-KNvka8We#WN*4Dk{&{Q>q)Xy%gJn*94d2~kMruGK@J{@rT-*)JD
z;n3hj>h2Jby5^kAv%I|aTn@ju4cJKua|UYVhx>k(4|l{5G0qloKmyH_5^VIiF}4@#
z^aoGZ(j>L#AXR346EonASdThw
zK6R+leE53ff=G^+o9XAFqV8MpvPtRH61v&(~;fk
zI_G0m7T@Wu=g_eOPi%Z}5?7%sSLuY}snE>Y-2}9AXj#4kZ1Q1lO-IZy>u_W@S*tIG
z{8eW?{-t_&|K!K@Ai8rDOx&0_uNaPikAWi%VS#CHPK7JZxJ0qvT^y|r&}7Q-_(Um%
zguTuux}P2DS
zUX%t*1O(V6(iW0Sw?1FfNS!)Lutx}ai^tCk2>K)uV<#ug%|Sm
zkviFWC-XCvC8lF!l1dzV2Vrwk8u4D~RYIUbr|3IX(whOiHbO=Uy!=ocO2`y4NDVBA
zyw)SLFLEpqx4TdFiEKqUnVNO709Xc>9#7#fMW9_s7=$$~D_SBRehHbYn!AHYPb<}Q
zeaiM06%y2PDquFxeHBS1Jjdr7DDT~B5Uk4#u=6dbTLeEU-$)g&I*-a?em
zYwY%j>IKNnXWaw0hXLi%j8>cK7CB7@9hW2mGiJG+PASxpnHKr-kaic-*eBr4dqYO#
zjBn6Mx;o{XO@jDOtXE7>^_0xs68k~46{DXGsq2)vR7%$CT@dRjHKJ(p5)ov^YdBP4B@{KGiV%FGFmHtF=W$v-ljq`jU6i)9ga&V*dgRE%aYJhH2%1c2;+*O
zo#b8FXf@hgM3_@gN^3MCBFl)Iz*R)&qwk8HYzI4n#=i~_Ny9gwwA@feQ=3t*Kv8rqNG(*9T_2rt{EQMe$}mwBad
zlpef`X~inqfxgB>yiVo|v#s5j0)lh&ssgPjug(suSY`B0T-f0FQ$u-ve!>;9NTr)(
z4AfV#Xte~=%U&aqw*sl6Ir{54n*?V2B}1?Ogf3(L9Y+v3xvXKRoEJhFx)cUJ6fvC6zB0?YS_*IdsaX!e4aw_5FI
z^blEjB-tnTAGg#6dus`#1k{!hoo|V>F+Ib*o!v$y8uFVR?^8Z{nG?QzOVGu*
z)%>&THA7}%V~UaL!*gn>{Ka?FwDyz9_tP?K+X!CR3KnTvl&>13amm`%VqjYS18}?XI%J9
z=H1s`T?JX?P9BzB%~~Hr)KJS$8a+vJO9EEA1YFj+A-7Vxj|YS6JMQZraNOYpVl(;l
zNUHY`HOm&{(>2}GZxUob^pu9G{4<2xgC`&E3K&PTwv}uy<;~Btv+yJ`NM49VMeg;^
z;#R91G%=9H=NZnp9D#XSwunsYN#^*f>74y%Pdy%A
zXAYuEPEyO@W?bZEk|N$MapcZJoIPKa@fKMM*6FCcdB3K{_3L=Mv>ZksTS}s6Gpj0B
e>h>7!0j1q2om+S!oblHuMJX|P(JEp6fd2xF6?&Nf

diff --git a/rest_api.md b/rest_api.md
index f88ba23..3921657 100644
--- a/rest_api.md
+++ b/rest_api.md
@@ -1,636 +1,4 @@
 # Crossref REST API
 
-
-
+[We have moved the main odcumentation page to](https://github.com/CrossRef/rest-api-doc)
 
-
-
-- [Service alert: 18 July 2017](#service-alert-18-july-2017)
-- [What's new: July 2017](#whats-new-july-2017)
-- [Preamble](#preamble)
-- [Meta](#meta)
-- [API overview](#api-overview)
-- [Result types](#result-types)
-- [Resource components](#resource-components)
-- [Parameters](#parameters)
-- [Queries](#queries)
-- [Field Queries](#field-queries)
-- [Sorting](#sorting)
-- [Facet counts](#facet-counts)
-- [Filter names](#filter-names)
-- [Result controls](#result-controls)
-- [API versioning](#api-versioning)
-- [Documentation history](#documentation-history)
-
-
-
-## Service alert: 18 July 2017
-
- Cited-by counts are not updating and should not be considered accurate. We are working on a fix and will update you ([see below](#learning-about-performanceavailability-problems)) when it is in place.
-
-## What's new: July 2017
-
-- References are now included if the publisher has made them public.
-- Metadata for preprints, listed as "posted-content"
-- Links from preprints to subsequent publications using "isPreprintOf" relationship
-- Abstracts for over 1 million DOIs
-- Subject categories have been updated to cover more of the content (~45,000 journal titles)
-- "is-referenced-by-count" - also known as cited-by counts.
-
-
-## Preamble
-
-The Crossref REST API is one of [a variety of tools and APIs](https://www.crossref.org/services/metadata-delivery/) that allow anybody to search and reuse our members' metadata in sophisticated ways.
-
-
-## Meta
-### Learning about performance or availability problems
-
-Note that we generally post notice any ongoing performance problems with our services on our twitter feeds at [CrossRefOrg](https://twitter.com/CrossrefOrg) and [CrossRefSupport](https://twitter.com/@CrossrefSupport). We also report them on our [support site](https://support.crossref.org/hc/en-us). You might want to check these to see if we are already aware of a problem before you report it.
-
-### Reporting performance or availability problems
-
-Report performance/availability at our [support site](https://support.crossref.org/hc/en-us).
-
-### Reporting bugs, requesting features ###
-
-Please report bugs with the API or the documentation on our [issue tracker](https://github.com/CrossRef/rest-api-doc/issues).
-
-### 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.
-
-### Privacy
-
-We also have a [privacy policy](https://www.crossref.org/privacy/).
-
-### Libraries
-
-You might be able to avoid reading all this documentation if you instead use one of the several excellent libraries that have been written for the Crossref REST API. For example:
-
-- [habanero](https://github.com/sckott/habanero) (Python)
-- [serrano](https://github.com/sckott/serrano) (Ruby)
-- [rcrossref](https://github.com/ropensci/rcrossref) (R)
-- [crossrefapi](https://github.com/fabiobatalha/crossrefapi) (Python)
-
-If you know of another library you would like to see listed here, please let us know about it via the [issue tracker](https://github.com/CrossRef/rest-api-doc/issues).
-
-### Etiquette
-
-We want to provide a public, open,  and free API for all. And we don't want to unnecessarily burden developers (or ourselves) with cumbersome API tokens or registration processes in order to use the public REST API. For that to work, we ask that you be polite and try not to do anything that will take the public REST API down or otherwise make it unusable for others. Specifically, we encourage the following polite behaviour:
-
-- Cache data so you don't request the same data over and over again. 
-- Actively monitor API response times. If they start to go up, back-off for a while. For example, add pauses between requests and/or reduce the number of parallel requests.
-- Specify a `User-Agent` header that properly identifies your script or tool and that provides some type of means of contacting you. For example:
-`GroovyBib/1.1 (https://example.org/GroovyBib/; GroovyBib@example.org) BasedOnFunkyLib/1.4`.
-
-This way we can contact you if we see a problem.
-
-- report problems and/or ask questions on our [issue tracker](https://github.com/CrossRef/rest-api-doc/issues).
-
-Alas, not all people are polite. And for this reason we reserve the right to impose rate limits and/or to block clients that are disrupting the public service.
-
-#### Rate limits
-
-From time to time Crossref needs to impose rate limits to ensure that the free API is usable by all. Any rate limits that are in effect will be advertised in the `X-Rate-Limit-Limit` and `X-Rate-Limit-Interval` HTTP headers.
-
-#### Blocking
-
-This is always our last resort, and you can generally avoid it if you include contact information in the `User-Agent` header as described above.
-
-But seriously... this is a bummer. We really want you to use the API. If you are polite about it, you shouldn't have any problems.
-
-### Use for production services
-
-What if you want to use our API for a production service that cannot depend on the performance uncertainties of the free and open public API? What if you don't want to be affected by impolite people who do not follow the [API Etiquette](#api-etiquette) guidelines? Well, if you’re interested in using these tools or APIs for production services, we’ll soon have a service-level offering with access to all supported APIs and metadata, but with extra service and support guarantees. If you are interested in the upcoming service-based offering please contact our [outreach team](mailto://member@crossref.org). 
-
-## API overview
-
-The API is generally RESTFUL and returns results in JSON. JSON formats returned by the API are documented [here](https://github.com/CrossRef/rest-api-doc/blob/master/api_format.md).
-
-The API supports HTTP and HTTPS. Examples here are provided using HTTPS.
-
-You should always url-encode DOIs and parameter values when using the API. DOIs are notorious for including characters that break URLs (e.g. semicolons, hashes, slashes, ampersands, question marks, etc.).
-
-Note that, for the sake of clarity, the examples in this document do *not* url-encode DOIs or parameter values. 
-
-The API will only work for Crossref DOIs. You can test the registration agency for a DOI using the following route:
-
-`https://api.crossref.org/works/{doi}/agency`
-
-Testing the following Crossref DOI:
-
-`10.1037/0003-066X.59.1.29`
-
-Using the URL:
-
-`https://api.crossref.org/works/10.1037/0003-066X.59.1.29/agency`
-
-Will return the following result:
-
-    {
-      status: "ok",
-      message-type: "work-agency",
-      message-version: "1.0.0",
-      message: {
-        DOI: "10.1037/0003-066x.59.1.29",
-        agency: {
-          id: "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.
-
-## Result types
-
-All results are returned in JSON. There are three general types of results:
-
-- Singletons
-- Headers-only
-- Lists
-
-The mime-type for API results is `application/vnd.crossref-api-message+json` 
-
-### Singletons
-
-Singletons are single results. Retrieving metadata for a specific identifier (e.g. DOI, ISSN, funder_identifier) typically returns in a singleton result.
-
-### Headers only
-
-You can use HTTP HEAD requests to quickly determine "existence" of a singleton. The advantage of this technique is that it is very fast because it does not return any metadata- it only retruns headers and an HTTP status code (200=exists, 404=does not exist).
-
-To determine if member ID `98` exists:
-
-`curl --head "http://api.crossref.org/members/98"`
-
-To determine if a journal with ISSN `1549-7712` exists:
-
-`curl --head "http://api.crossref.org/journals/1549-7712"`
-
-### Lists
-Lists results can contain multiple entries. Searching or filtering typically returns a list result. A list has two parts:
-
-- Summary, which include the following information:
-
-    - status (e.g. "ok", error)
-    - message-type (e.g. "work-list" )
-    - message-version (e.g. 1.0.0 )
-    
-- Items, which will will contain the items matching the query or filter. 
-
-Note that the "message-type" returned will differ from the mime-type:
-
-- funder (singleton)
-- prefix (singleton)
-- member (singleton)
-- work (singleton)
-- work-list (list)
-- funder-list (list)
-- prefix-list (list)
-- member-list (list)
-
-Normally, an API list result will return both the summary and the items. If you want to just retrieve the summary, you can do so by specifying that the number of rows returned should be zero. 
-
-#### Sort order
-
-If the API call includes a query, then the sort order will be by the relevance score. If no query is included, then the sort order will be by DOI update date.
-
-
-## Resource components
-Major resource components supported by the Crossref API are:
-
-- works
-- funders
-- members
-- prefixes
-- types
-- journals
-
-These can be used alone like this
-
-| resource      | description                       |
-|:--------------|:----------------------------------|
-| `/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 [Funder Registry](https://github.com/CrossRef/open-funder-registry
-| `/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 |
-
-
-### 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. |
-| `/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 |
-| `/types/{type_id}` | returns information about a metadata work type |
-| `/journals/{issn}` | returns information about a journal with the given ISSN |
-
-### Combining resource components
-
-The works component can be appended to other resources.
-
-| resource                    | description                       |
-|:----------------------------|:----------------------------------|
-| `/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) |
-| `/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.
-
-| parameter                    | description                 |
-|:-----------------------------|:----------------------------|
-| `query`                      | query terms |
-| `filter={filter_name}:{value}`| filter results by specific fields |
-| `rows={#}`                   | results per per page | 
-| `offset={#}` (mak 10k)               | result offset (user `cursor` for larger `/works` result sets)  |                         
-| `sample={#}` (max 100)                | return random N results |
-| `sort={#}`                   | sort results by a certain field |
-| `order={#}`                  | set the sort order to `asc` or `desc` |
-| `facet={#}`                    | enable facet information in responses |
-| `cursor={#}`		       | deep page through `/works` result sets |
-
-Multiple filters can be specified by separating name:value pairs with a comma:
-
-    https://api.crossref.org/works?filter=has-orcid:true,from-pub-date:2004-04-04
-
-### Example query using URI parameters
-
-    https://api.crossref.org/funders/100000015/works?query=global+state&filter=has-orcid:true&rows=1
-
-## Queries
-
-Free form search queries can be made, for example, works that include `renear` and `ontologies`:
-
-    https://api.crossref.org/works?query=renear+ontologies
-	
-## Field Queries
-
-Field queries are available on the `/works` route and allow for queries that match only particular fields
-of metadata. For example, this query matches records that contain the tokens `richard` or `feynman` (or both)
-in any author field:
-
-    https://api.crossref.org/works?query.author=richard+feynman
-	
-Field queries can be combined with the general `query` paramter and each other. Each query parameter
-is ANDed with the others:
-
-    https://api.crossref.org/works?query.title=room+at+the+bottom&query.author=richard+feynman
-	
-### `/works` Field Queries
-
-These field queries are available on the `/works` route:
-
-| Field query parameter | Description |
-|-----------------------|-------------|
-| `query.title` | Query `title` and `subtitle` |
-| `query.container-title` | Query `container-title` aka. publication name |
-| `query.author` | Query author given and family names |
-| `query.editor` | Query editor given and family names |
-| `query.chair` | Query chair given and family names |
-| `query.translator` | Query translator given and family names |
-| `query.contributor` | Query author, editor, chair and translator given and family names |
-| `query.bibliographic` | Query bibliographic infomration, useful for citation look up. Includes titles, authors, ISSNs and publication years |
-| `query.affiliation` | Query contributor affiliations |
-
-## Sorting
-
-Results from a listy response can be sorted by applying the `sort` and `order` parameters. Order
-sets the result ordering, either `asc` or `desc`. Sort sets the field by which results will be
-sorted. Possible values are:
-
-| Sort value | Description |
-|------------|-------------|
-| `score` or `relevance` | Sort by relevance score |
-| `updated` | Sort by date of most recent change to metadata. Currently the same as `deposited`. |
-| `deposited` | Sort by time of most recent deposit |
-| `indexed` | Sort by time of most recent index |
-| `published` | Sort by publication date |
-| `published-print` | Sort by print publication date |
-| `published-online` | Sort by online publication date |
-| `issued` | Sort by issued date (earliest known publication date) |
-| `is-referenced-by-count` | Sort by number of references to documents |
-| `references-count` | Sort by number of references made by documents |
-
-An example that sorts results in order of publication, beginning with the least recent:
-
-    https://api.crossref.org/works?query=josiah+carberry&sort=published&order=asc
-
-## Facet counts
-
-Facet counts can be retrieved by enabling faceting. Facets are enabled by providing facet field names along with a maximum number of returned term values. The larger the number of returned values, the longer the query will take. Some facet fields
-can accept a `*` as their maximum, which indicates that all values should be returned.
-
-Facets are specified with the `facet` parameter:
-
-    https://api.crossref.org/works?rows=0&facet=type-name:*
-    
-| Facet name | Maximum values | Description |
-|:-----------|:---------------|-------------|
-| `affiliation` | `*` | Author affiliation | 
-| `year` | `*` | Earliest year of publication, synonym for `published` |
-| `funder-name` | `*` | Funder literal name as deposited alongside DOIs |
-| `funder-doi` | `*` | Funder DOI |
-| `orcid` | 100 | Contributor ORCID | 
-| `container-title` | 100 | Work container title, such as journal title, or book title |
-| `assertion` | `*` | Custom Crossmark assertion name |
-| `archive` | `*` | Archive location |
-| `update-type` | `*` | Significant update type |
-| `issn` | 100 | Journal ISSN (any - print, electronic, link) |
-| `published` | `*` | Earliest year of publication |
-| `type-name` | `*` | Work type name, such as `journal-article` or `book-chapter` |
-| `license` | `*` | License URI of work |
-| `category-name` | `*` | Category name of work |
-| `relation-type` | `*` | Relation type described by work or described by another work with work as object |
-| `assertion-group` | `*` | Custom Crossmark assertion group name |
-
-## Filter names
-
-Filters allow you to narrow queries. All filter results are lists.  The following filters are supported:
-
-| filter     | possible values | description|
-|:-----------|:----------------|:-----------|
-| `has-funder` | | metadata which includes one or more funder entry |
-| `funder` | `{funder_id}` | metadata which include the `{funder_id}` in FundRef data |
-| `location` |`{country_name}` | funder records where location = `{country name}`. Only works on `/funders` route |
-| `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 |
-| `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}` |
-| `until-deposit-date` | `{date}` | metadata last (re)deposited before (inclusive) `{date}` |
-| `from-update-date` | `{date}` | Metadata updated since (inclusive) `{date}`. Currently the same as `from-deposit-date`. |
-| `until-update-date` | `{date}` | Metadata updated before (inclusive) `{date}`. Currently the same as `until-deposit-date`. |
-| `from-created-date` | `{date}` | metadata first deposited since (inclusive) `{date}` |
-| `until-created-date` | `{date}` | metadata first deposited before (inclusive) `{date}` |
-| `from-pub-date` | `{date}` | metadata where published date is since (inclusive) `{date}` |
-| `until-pub-date` | `{date}` | metadata where published date is before (inclusive)  `{date}` |
-| `from-online-pub-date` | `{date}` | metadata where online published date is since (inclusive) `{date}` |
-| `until-online-pub-date` | `{date}` | metadata where online published date is before (inclusive)  `{date}` |
-| `from-print-pub-date` | `{date}` | metadata where print published date is since (inclusive) `{date}` |
-| `until-print-pub-date` | `{date}` | metadata where print published date is before (inclusive)  `{date}` |
-| `from-posted-date` | `{date}` | metadata where posted date is since (inclusive) `{date}` |
-| `until-posted-date` | `{date}` | metadata where posted date is before (inclusive)  `{date}` |
-| `from-accepted-date` | `{date}` | metadata where accepted date is since (inclusive) `{date}` |
-| `until-accepted-date` | `{date}` | metadata where accepted date is before (inclusive)  `{date}` |
-| `has-license` | | metadata that includes any `` elements. |
-| `license.url` | `{url}` | metadata where `` value equals `{url}` |
-| `license.version` | `{string}` | metadata where the ``'s `applies_to` attribute  is `{string}`|
-| `license.delay` | `{integer}` | metadata where difference between publication date and the ``'s `start_date` attribute is <= `{integer}` (in days)|
-| `has-full-text` |  | metadata that includes any full text `` elements. |
-| `full-text.version` | `{string}`  | metadata where `` element's `content_version` attribute is `{string}`. |
-| `full-text.type` | `{mime_type}`  | metadata where `` element's `content_type` attribute is `{mime_type}` (e.g. `application/pdf`). |
-| `has-references` | | metadata for works that have a list of references |
-| `has-archive` | | metadata which include name of archive partner |
-| `archive` | `{string}` | metadata which where value of archive partner is `{string}` |
-| `has-orcid` | | metadata which includes one or more ORCIDs |
-| `has-authenticated-orcid` | | metadata which includes one or more ORCIDs where the depositing publisher claims to have witness the ORCID owner authenticate with ORCID |
-| `orcid` | `{orcid}` | metadata where `` element's value = `{orcid}` |
-| `issn` | `{issn}` | metadata where record has an ISSN = `{issn}`. Format is `xxxx-xxxx`. |
-| `type` | `{type}` | metadata records whose type = `{type}`. Type must be an ID value from the list of types returned by the `/types` resource |
-| `directory` | `{directory}` | metadata records whose article or serial are mentioned in the given `{directory}`. Currently the only supported value is `doaj`. |
-| `doi` | `{doi}` | metadata describing the DOI `{doi}` |
-| `updates` | `{doi}` | metadata for records that represent editorial updates to the DOI `{doi}` |
-| `is-update` | | metadata for records that represent editorial updates |
-| `has-update-policy` | | metadata for records that include a link to an editorial update policy |
-| `container-title` | | metadata for records with a publication title exactly with an exact match |
-| `category-name` | | metadata for records with an exact matching category label. Category labels come from [this list](https://www.elsevier.com/solutions/scopus/content) published by Scopus |
-| `type` | | metadata for records with type matching a type identifier (e.g. `journal-article`) |
-| `type-name` | | metadata for records with an exacty matching type label |
-| `award.number` | `{award_number}` | metadata for records with a matching award nunber. Optionally combine with `award.funder` |
-| `award.funder` | `{funder doi or id}` | metadata for records with an award with matching funder. Optionally combine with `award.number` |
-| `has-assertion` | | metadata for records with any assertions |
-| `assertion-group` | | metadata for records with an assertion in a particular group |
-| `assertion` | | metadata for records with a particular named assertion |
-| `has-affiliation` | | metadata for records that have any affiliation information |
-| `alternative-id` | | metadata for records with the given alternative ID, which may be a publisher-specific ID, or any other identifier a publisher may have provided |
-| `article-number` | | metadata for records with a given article number |
-| `has-abstract` | | metadata for records which include an abstract |
-| `has-clinical-trial-number` | | metadata for records which include a clinical trial number |
-| `content-domain` | | metadata where the publisher records a particular domain name as the location Crossmark content will appear |
-| `has-content-domain` | | metadata where the publisher records a domain name location for Crossmark content |
-| `has-crossmark-restriction` | | metadata where the publisher restricts Crossmark usage to content domains |
-| `has-relation` | | metadata for records that either assert or are the object of a relation |
-| `relation.type` | | One of the relation types from the Crossref relations schema (e.g. `is-referenced-by`, `is-parent-of`, `is-preprint-of`) |
-| `relation.object` | | Relations where the object identifier matches the identifier provided |
-| `relation.object-type` | | One of the identifier types from the Crossref relations schema (e.g. `doi`, `issn`) |
-
-### Multiple filters
-
-Multiple filters can be specified in a single query. In such a case, different filters will be applied with AND semantics, while specifying the same filter multiple times will result in OR semantics - that is, specifying the filters:
-
-- `is-update:true`
-- `from-pub-date:2014-03-03`
-- `funder:10.13039/100000001`
-- `funder:10.13039/100000050`
-
-would locate documents that are updates, were published on or after 3rd March 2014 and were funded by either the National Science Foundation (`10.13039/100000001`) or the National Heart, Lung, and Blood Institute (`10.13039/100000050`). These filters would be specified by joining each filter together with a comma:
-
-    /works?filter=is-update:true,from-pub-date:2014-03-03,funder:10.13039/100000001,funder:10.13039/100000050
-    
-### Dot filters
-
-A filter with a dot in its name is special. The dot signifies that the filter will be applied to some other record type that is related to primary resource record type. For example, with work queries, one can filter on works that have an award, where the same award has a particular award number and award-gving funding agency:
-
-    /works?filter=award.number:CBET-0756451,award.funder:10.13039/100000001
-    
-Here we filter on works that have an award by the National Science Foundation that also has the award number `CBET-0756451`.
-
-### 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. 
-
-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. 
-
-### Notes on incremental metadata updates
-
-When using time filters to retrieve periodic, incremental metadata updates,
-the `from-index-date` filter should be used over `from-update-date`,
-`from-deposit-date`, `from-first-deposit-date` and `from-pub-date`. The
-timestamp that `from-index-date` filters on is guaranteed to be updated
-every time there is a change to metadata requiring a reindex.
-
-## Result controls
-
-You can control the delivery and selection results using the `rows`, `offset` and `sample` parameters.
-
- If you are expecting results beyond 10K, then use a `cursor` to deep page through the results. Note that not all routes support cursors.
-
-### Rows 
-
-Normally, results are returned 20 at a time. You can control the number of results returns by using the `rows` parameter. To limit results to 5, for example, you could do the following:
-
-    https://api.crossref.org/works?query=allen+renear&rows=5
-
-If you would just like to get the `summary` of the results, you can set the rows to 0 (zero).
-
-    https://api.crossref.org/works?query=allen+renear&rows=0
-    
-The maximum number rows you can ask for in one query is `1000`.
-
-### Offset
-
-The number of returned items is controlled by the `rows` parameter, but you can select the offset into the result list by using the `offset` parameter.  So, for example, to select the second set of 5 results (i.e. results 6 through 10), you would do the following:
-
-    https://api.crossref.org/works?query=allen+renear&rows=5&offset=5
-
-Offsets for `/works` are limited to 10K. Use `cursor` (see below) for larger `/works` results sets.
-
-### Deep paging with cursors
-
-Using large `offset` values can result in extremely long response times. Offsets in the 100,000s and beyond will likely cause a timeout before the API is able to respond. An alternative to paging through very large result sets (like a corpus used for text and data mining) it to use the API's exposure of Solr's deep paging cursors. Any combination of query, filters and facets may be used with deep paging cursors. While `rows` may be specified along with `cursor`, `offset` and `sample` cannot be used. To use deep paging make a query as normal, but include the `cursor` parameter with a value of `*`. In this example we will page through all `journal-article` works from member `311`:
-
-    https://api.crossref.org/members/311/works?filter=type:journal-article&cursor=*
-
-A `next-cursor` field will be provided in the JSON response. To get the next page of results, pass the value of `next-cursor` as the `cursor` parameter:
-
-    https://api.crossref.org/members/311/works?filter=type:journal-article&cursor=AoE/CGh0dHA6Ly9keC5kb2kub3JnLzEwLjEwMDIvdGRtX2xpY2Vuc2VfMQ==
- 
-Clients should check the number of returned items. If the number of returned items is fewer than the number of expected rows then the end of the result set has been reached. Using `next-cursor` beyond this point will result in responses with an empty items list.
-
-The `cursor` parameter is available on all `/works` resources.
-
-### Sample
-
-Being able to select random results is useful for both testing and sampling. You can use the `sample` parameter to retrieve random results. So, for example, the following select 10 random works:
-
-    https://api.crossref.org/works?sample=10
-    
-Note that when you use the `sample` parameter, the `rows` and `offset` parameters are ignored.
-
-
-### Example queries
-
-**All works published by owner prefix `10.1016` in January 2010**
-
-    https://api.crossref.org/prefixes/10.1016/works?filter=from-pub-date:2010-01,until-pub-date:2010-01
-
-**All works funded by `10.13039/100000001` that have a CC-BY license**
-
-    https://api.crossref.org/funders/10.13039/100000001/works?filter=license.url:http://creativecommons.org/licenses/by/3.0/
-
-**All works published by owner prefix 10.6064 from February 2010 to February 2013 that have a CC-BY license**
-
-    https://api.crossref.org/prefixes/10.6064/works?filter=license.url:http://creativecommons.org/licenses/by/3.0/,from-pub-date:2010-02,until-pub-date:2013-02
-
-**All works funded by `10.13039/100000015` where license = CC-BY and embargo <= 365 days**
-
-    https://api.crossref.org/funders/10.13039/100000015/works?filter=license.url:http://creativecommons.org/licenses/by/3.0/,license.delay:365
-
-Note that the filters for license URL and maximum license embargo period (license.url and license.delay) combine to filter each document's metadata for a license with both of these properties.
-
-**All works where the archive partner listed = 'CLOCKSS'**
-
-    https://api.crossref.org/works?filter=archive:CLOCKSS
-    
-**All members with `hind` in their name (e.g. Hindawi)**
-
-    https://api.crossref.org/members?query=hind
-    
-**All licenses linked to works published by Elsevier**
-
-    http://api.crossref.org/v1/works?facet=license:*&filter=member:78&rows=0
-    
-**All licenses applied to works published in the journal `Pathology Research International`**
-
-    https://api.crossref.org/works?facet=license:*&filter=issn:2090-8091
-    
-**All works with an award numbered roughly `1 F31 MH11745` also awarded by funder with ID `10.13039/100000025`:
-
-    https://api.crossref.org/works?filter=award.number:1F31MH11745,award.funder:10.13039/100000025
-
-## API versioning
-
-In theory, the syntax of the API can vary independently of the result representations. In practice, major version changes in either will require changes to API clients and so versioning of the API will apply to both the API syntax and the result representation.
-
-The API uses a semantic versioning scheme whereby the version number is divided into three parts delimited by periods. The first number represents the "major" release number. The second represents a "minor" release number.
-      
-    Version 1.20
-            ^  ^
-            |  |
-        major  |
-           minor
-
- **Major** version increments 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 Crossref can roll out. Note that client applications should not have dependencies on minor versions, and Crossref will only maintain the latest minor version for the two most recent major versions.
-
-Adding syntax options or metadata to representations will normally be backwards compatible and will thus normally only trigger minor version changes. Renaming or restructuring syntax options of metadata tends not to be backward compatible and will thus typically trigger major version changes
-
-### How to manage API versions
-
-If you need to tie your implementation to a specific major version of the API, you can do so by using version-specific routes. The default route redirects to the most recent version of the API. Some older major versions may be available using a version prefix. For example, to access version `v1` of the API:
-
-    https://api.crossref.orv/v1/works
-    
-Each major version has no backwards incompatible changes within its public interface.
-
-## Documentation history
-
-- V1: 2013-09-08, first draft.
-- V2: 2013-09-24, reference platform deployed
-- v3: 2013-09-25, reworked filters. Added API versioning doc 
-- v4: 2013-09-25, more filter changes.
-- v5: 2013-09-27, doc mime-type and message-type relationship
-- v6: 2013-10-01, updated `sample` & added examples with filters
-- v6: 2013-10-01, corrected warning date
-- v7: 2013-10-02, fixed typos
-- v8: 2013-10-17, updated warning. Added email address
-- v9: 2013-12-13, update example urls
-- v10: 2013-12-13, /types routes, type filter, issn filter
-- v11: 2013-12-14, indexed timestamps, has-archive and archive implemented
-- v12: 2014-01-06, directory filter
-- v13: 2014-02-10, new `/members`, `/publishers` becomes `/prefixes`, new `member` filter, `publisher` filter becomes `prefix`
-- v14: 2014-02-14, new `has-funder` filter.
-- v15: 2014-02-27, new `/licenses` route
-- v16: 2014-05-19, new `/journals` route, new CrossMark (updates and update policy) filters, new `sort` and `order` parameters
-- v17: 2014-05-19, new `facet` query parameter
-- v18: 2014-05-29, new `/works/{doi}/agency` route
-- v19: 2014-06-23, new textual filters - `container-title`, `category-name`.
-- v20: 2014-06-24, OR filter queries, `type-name` filter.
-- 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.
-- 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
-- v28, 2016-05-09, added link to source of category lables
-- v29, 2016-05-24, added field queries
-- v30, 2016-09-26, highlight issue tracker
-- v31, 2016-10-05, document `has-clinical-trial-number` and `has-abstract` filters
-- v32, 2016-10-27, document rate limit headers
-- v33, 2016-11-07, guidance on when to use `offset` vs `cursor`
-- v34, 2017-04-26, document support for HTTPS. Update examples to use HTTPS.
-- v35, 2017-04-26, document use of head reqeusts to determine `existence`
-- v36, 2017-04-27, fixed license route examples to use facet/filter instead
-- v37, 2017-04-27, `query.bibliographic`
-- v38, 2017-04-27, add v1.1 filters and sort fields
-- v39, 2017-04-27, remove mention of dismax
-- v40, 2017-04-27, clarify faceting feature
-- v41, 2017-04-28, document `sample` max = 100, clarify cursors only work on some routes
-- v42, 2017-04-28, life, the universe, and everything
-- v43, 2017-04-28, reminder on the wisdom of url-encoding
-- v44, 2017-04-28, clarify that field queries apply to `/works` route
-- v45, 2017-04-28, document `location` filter for `/funders` route
-- v46, 2017-06-14, minor text changes and new funder registry link
-- v47, 2017-07-04, clarify `query.affiliation`
-- v48, 2017-07-13, correct "first and given" names to "given and family"
-- v49, 2017-07-20, move document version history, add section on libraries
-- v50, 2017-07-20, add TOC, move document history, add etiquet section, add production use section, general formatting + cleanup

From 28d57f33e37513ab3774713f59e1fba13f3ac963 Mon Sep 17 00:00:00 2001
From: Geoffrey Bilder 
Date: Thu, 20 Jul 2017 14:25:29 +0200
Subject: [PATCH 166/219] typos

---
 rest_api.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/rest_api.md b/rest_api.md
index 3921657..d73f454 100644
--- a/rest_api.md
+++ b/rest_api.md
@@ -1,4 +1,4 @@
 # Crossref REST API
 
-[We have moved the main odcumentation page to](https://github.com/CrossRef/rest-api-doc)
+[We have moved the main documentation page.](https://github.com/CrossRef/rest-api-doc)
 

From 009319c59dc7a7fe6310c04ed92ac0a0ce761f33 Mon Sep 17 00:00:00 2001
From: Geoffrey Bilder 
Date: Thu, 20 Jul 2017 14:53:09 +0200
Subject: [PATCH 167/219] cleanup links in funder kpis doc

---
 funder_kpi_metadata_best_practice.md | 22 +++++++++-------------
 1 file changed, 9 insertions(+), 13 deletions(-)

diff --git a/funder_kpi_metadata_best_practice.md b/funder_kpi_metadata_best_practice.md
index 1474e38..21df94c 100644
--- a/funder_kpi_metadata_best_practice.md
+++ b/funder_kpi_metadata_best_practice.md
@@ -53,9 +53,7 @@
 
 ## Contact info
 
-If you encounter problems with the API or the documentation, please report them to:
-
-![](http://labs.crossref.org/wp-content/uploads/2013/01/labs_email.png)
+If you encounter problems with the API or the documentation, please report them using our [issue tracker](https://github.com/CrossRef/rest-api-doc/issues).
 
 ## Background
 
@@ -63,7 +61,7 @@ Funders are increasingly setting mandates around publications that result from r
 
 Crossref has extended its metadata schemas and Application Programming Interfaces (APIs) to enable funding agencies, institutions and publishers to use Crossref as a metadata source that can be used to track research that is subject to these mandates and to ensure that said research is being disseminated according to the requirements of the mandates.
 
-Funders, institutions, publishers and third parties providing research information management tools (e.g. *[CHORUS](http://publishers.org/press/107/)*, *[SHARE](http://www.arl.org/news/arl-news/2773-shared-access-research-ecosystem-proposed-by-aau-aplu-arl)*,*[Symplectic](http://symplectic.co.uk)* can make use of Crossref APIs and metadata in order to identify:
+Funders, institutions, publishers and third parties providing research information management tools (e.g. *[CHORUS](https://www.chorusaccess.org/)*, *[SHARE](http://www.arl.org/news/arl-news/2773-shared-access-research-ecosystem-proposed-by-aau-aplu-arl)*,*[Symplectic](http://symplectic.co.uk)* can make use of Crossref APIs and metadata in order to identify:
 
 - Publications relating to research supported by particular funders.
 - Publications from particular researchers identified by their ORCID ID.
@@ -118,7 +116,7 @@ In order to alert funders of relevant publications as soon as possible, Crossref
 
 ## Funding information
 
-Crossref supports the recording of funding information for a publication via its [Funding Data](http://www.crossref.org/fundingdata/index.html) program. The Open Funder Registry defines an open, standard [registry of funder names and funder identifiers](http://www.crossref.org/fundingdata/registry.html) that can be used in order to increase the accuracy of the funding information recorded. Although Funding Data supports recording award_numbers along with funder identifiers, Crossref does __not__ define standards for recording award numbers as practice varies greatly across funders.
+Crossref supports the recording of funding information for a publication via its [Funding Data](http://www.crossref.org/fundingdata/index.html) program. The Open Funder Registry defines an open, standard [registry of funder names and funder identifiers](https://www.crossref.org/services/funder-registry/) that can be used in order to increase the accuracy of the funding information recorded. Although Funding Data supports recording award_numbers along with funder identifiers, Crossref does __not__ define standards for recording award numbers as practice varies greatly across funders.
 
 To support funder KPIs, members __must__ deposits funder metadata using the specifications defined for the Funder Data program. Specifically, when depositing metadata you:
 
@@ -128,7 +126,7 @@ To support funder KPIs, members __must__ deposits funder metadata using the spec
 3. __should__ include award numbers in Funder Data when possible. Although the standard KPI API does not make direct use of award numbers, individual agencies may be able to make use of included award numbers where found.
 4. __should__ deposit Funder Data as part of a CrossMark record if you (the publisher) already are (or *are planning* to become) a participant in CrossMark. There are two reasons for this: First, it ensures that the Funder Data is available __both__ in a standard machine readable format __AND__ via a standard UI for readers. Second, it ensures that the Funder Data is made maximally reusable via a CC Zero license waiver. Note that publishers do not __need__ to have implemented CrossMark yet to deposit Funder metadata via CrossMark. We expect that publishers may take a year or more before they have fully implemented all of CrossMark's features.
 
-See Crossref's Help pages for [Technical details on depositing Funder Data.](http://help.crossref.org/#fundref)
+See Crossref's Help pages for [Technical details on depositing Funder Data.](https://support.crossref.org/hc/en-us/articles/214360746-Funding-data-overview)
 
 ## License information
 
@@ -198,7 +196,7 @@ Note that, by recording a `` that points to the full text, you are not
 
 Note also that the publisher could theoretically choose only to deposit `` elements for full text representations once an embargo has ended. However, this approach may prove fraught, as any mistakes or delays in the redeposit process might lead the funding agency to believe that the publisher has not made the relevant content accessible at the end of the embargo period.
 
-Further detail on using the `` element for recording links to full text can be found on the [Prospect support site](http://prospectsupport.labs.crossref.org/full-text-uris-technical-details/) and in the Crossref deposit schema documentation for the [ `` ](http://www.crossref.org/schema/documentation/4.3.4/4.3.4.html#collection) and [ `` ](http://www.crossref.org/schema/documentation/4.3.4/4.3.4.html#resource) elements.
+Further detail on using the `` element for recording links to full text can be found on the [Text & data mining support site](https://support.crossref.org/hc/en-us/articles/214298866-Full-Text-URIs-Technical-Details) and in the Crossref deposit schema documentation for the [ `` ](http://data.crossref.org/reports/help/schema_doc/4.4.0/schema_4_4_0.html#collection) and [ `` ](http://data.crossref.org/reports/help/schema_doc/4.4.0/schema_4_4_0.html#resource) elements.
 
 ## Different licenses for different versions of the content
 
@@ -289,7 +287,7 @@ Publishers can record the archive arrangement or archive intention of a document
 	  
         
 
-Crossref maintains a vocabulary of archive locations within the Crossref deposit schema. The latest list of possible archive location values can be found in the documentation for the [ `` element ](http://www.crossref.org/help/schema_doc/4.3.6/4.3.6.html).
+Crossref maintains a vocabulary of archive locations within the Crossref deposit schema. The latest list of possible archive location values can be found in the documentation for the [ `` element ](http://data.crossref.org/reports/help/schema_doc/4.4.0/schema_4_4_0.html#archive).
 
 ## Assigning and registering DOIs at acceptance
 
@@ -307,8 +305,6 @@ Crossref has always supported the deposit of DOIs for accepted manuscripts __if_
 
 ### Assigning and registering DOIs for manuscripts that the publisher *has not yet* made available online
 
-*(Please note that this section includes a draft rules and guidelines. These are being finalised and this section will be updated accordingly)*
-
 Crossref will support a new mechanism and workflow to support the registration of DOIs for accepted manuscripts __before__ they are made publicly available online. This feature can be used by publishers as a mechanism for informing funders and institutions of impending publications. To use this, publishers will deposit a special type of Crossref record called "registered content."
 
 The schema and rules governing the "registered content" type attempt to balance the publisher's desire to control publicity around their content with the requirements that funders and institutions have to know as soon as possible when content governed under their mandates has been accepted for publication. Once the publication is made available online (either as an accepted manuscript or version of record), then the publisher can simply redeposit and replace the "registered content" record with a full metadata record using a Crossref schema appropriate to the publication (e.g. journal article).
@@ -386,7 +382,7 @@ Crossref supports the deposit of abstracts conforming to the [JATS](http://jats.
 
 **Q:** What license applies to the metadata retrieved by the [Crossref APIs to support key performance indicators (KPIs) for funding agencies](funder_kpi_api.html)?
 
    
-**A:** 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/).
+**A:** 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. 
 
 **Q:** What does it mean if a `` element has no `start_date` attribute?
 
    
@@ -410,14 +406,14 @@ Crossref supports the deposit of abstracts conforming to the [JATS](http://jats.
 
 ### Full Deposits
 
-Full deposits use the [standard deposit schema](http://www.crossref.org/schema/deposit/crossref4.3.4.xsd).
+Full deposits use the [standard deposit schema](http://data.crossref.org/reports/help/schema_doc/4.4.0/4.4.0.html).
 
 - [Full deposit](examples/full.xml)
 - [Full deposit with CrossMark](examples/full-crossmark.xml)
 
 ### Partial Deposits
 
-Partial deposits use the [resource deposit schema](http://doi.crossref.org/schemas/doi_resources4.3.2.xsd).
+Partial deposits use the [resource deposit schema](http://data.crossref.org/schemas/doi_resources4.3.2.xsd).
 
 Partial deposits update only part of a DOI's metadata. In the Crossref help system
 they are referred to as **resource deposits**, but it is not just resources that can

From 186be422a42c8b4c06bca1f730a5e3854cd56f28 Mon Sep 17 00:00:00 2001
From: Geoffrey Bilder 
Date: Thu, 20 Jul 2017 14:55:11 +0200
Subject: [PATCH 168/219] bump document version

---
 funder_kpi_metadata_best_practice.md | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/funder_kpi_metadata_best_practice.md b/funder_kpi_metadata_best_practice.md
index 21df94c..13b93f5 100644
--- a/funder_kpi_metadata_best_practice.md
+++ b/funder_kpi_metadata_best_practice.md
@@ -35,7 +35,7 @@
 
 
 
-## Version History
+## Document Version History
 
 - V01: 2013-09-08, first draft.
 - V02: 2013-09-09, add examples + links.
@@ -50,6 +50,7 @@
 - v11: 2013-12-11, Added third party archive arrangements section. Updated examples to include archive locations.
 - v12: 2015-11-27, Revisions to describe deposit workflow to support alerting funders/instituions when content has been "accepted". Pointers to latest schemas. General cleanup.
 - v13: 2016-03-22, Updated mentions of "FunRef" to "Funding Data" and "Open Funder Registry" as appropriate. Updated "CrossRef" to "Crossref." Updated section on registered content to indicate impending finalization of process. 
+- v14: 2017-07-20, Cleanup links.
 
 ## Contact info
 

From 954f45674e25337c715b5ca4a18164ee3013bdd9 Mon Sep 17 00:00:00 2001
From: Geoffrey Bilder 
Date: Thu, 20 Jul 2017 16:48:38 +0200
Subject: [PATCH 169/219] make suggested user agent string regex friendly

---
 README.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/README.md b/README.md
index f88ba23..17a2c48 100644
--- a/README.md
+++ b/README.md
@@ -83,7 +83,7 @@ We want to provide a public, open,  and free API for all. And we don't want to u
 - Cache data so you don't request the same data over and over again. 
 - Actively monitor API response times. If they start to go up, back-off for a while. For example, add pauses between requests and/or reduce the number of parallel requests.
 - Specify a `User-Agent` header that properly identifies your script or tool and that provides some type of means of contacting you. For example:
-`GroovyBib/1.1 (https://example.org/GroovyBib/; GroovyBib@example.org) BasedOnFunkyLib/1.4`.
+`GroovyBib/1.1 (https://example.org/GroovyBib/; mailto:GroovyBib@example.org) BasedOnFunkyLib/1.4`.
 
 This way we can contact you if we see a problem.
 

From b952ab221ec6fd348fd7c8ea6374be9d5bc62047 Mon Sep 17 00:00:00 2001
From: Geoffrey Bilder 
Date: Mon, 24 Jul 2017 08:24:47 +0200
Subject: [PATCH 170/219] fix broken link in markdown

---
 README.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/README.md b/README.md
index 17a2c48..d2c84d1 100644
--- a/README.md
+++ b/README.md
@@ -214,7 +214,7 @@ These can be used alone like this
 | resource      | description                       |
 |:--------------|:----------------------------------|
 | `/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 [Funder Registry](https://github.com/CrossRef/open-funder-registry
+| `/funders`    | returns a list of all funders in the [Funder Registry](https://github.com/CrossRef/open-funder-registry)
 | `/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 |

From 7cf64df5d945d103cbbc075a3d96b81ec7cc7fc9 Mon Sep 17 00:00:00 2001
From: Geoffrey Bilder 
Date: Mon, 24 Jul 2017 08:58:30 +0200
Subject: [PATCH 171/219] clarified license of the documentation (as opposed to
 metadata)

---
 LICENSE   | 1 +
 README.md | 6 +++++-
 2 files changed, 6 insertions(+), 1 deletion(-)
 create mode 100644 LICENSE

diff --git a/LICENSE b/LICENSE
new file mode 100644
index 0000000..5f19d88
--- /dev/null
+++ b/LICENSE
@@ -0,0 +1 @@
+This work is licensed under the Creative Commons Attribution 4.0 International License. To view a copy of this license, visit http://creativecommons.org/licenses/by/4.0/ or send a letter to Creative Commons, PO Box 1866, Mountain View, CA 94042, USA.
\ No newline at end of file
diff --git a/README.md b/README.md
index d2c84d1..6d013e8 100644
--- a/README.md
+++ b/README.md
@@ -56,8 +56,11 @@ Report performance/availability at our [support site](https://support.crossref.o
 
 Please report bugs with the API or the documentation on our [issue tracker](https://github.com/CrossRef/rest-api-doc/issues).
 
-### License
+### Documentation License
 
+Creative Commons License
    This work is licensed under a Creative Commons Attribution 4.0 International License.
+
+### Metadata 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.
 
@@ -634,3 +637,4 @@ Each major version has no backwards incompatible changes within its public inter
 - v48, 2017-07-13, correct "first and given" names to "given and family"
 - v49, 2017-07-20, move document version history, add section on libraries
 - v50, 2017-07-20, add TOC, move document history, add etiquet section, add production use section, general formatting + cleanup
+- v51, 2017-07-24, clarified license of the documentation (as opposed to metadata)

From 53c85a7471372ed52d4a129c758dfca75345c925 Mon Sep 17 00:00:00 2001
From: Karl Jonathan Ward 
Date: Wed, 26 Jul 2017 11:54:00 +0100
Subject: [PATCH 172/219] Mention abstract and authenticated-orcid

Fixes CrossRef/rest-api-doc#253
---
 api_format.md | 7 +++++--
 1 file changed, 5 insertions(+), 2 deletions(-)

diff --git a/api_format.md b/api_format.md
index a40c5b3..a4c0255 100644
--- a/api_format.md
+++ b/api_format.md
@@ -5,6 +5,7 @@
 | Version | Release Date | Comments |
 |---------|--------------|----------|
 | v1 | 11th July 2016 | First documented version |
+| v2 | 26th July 2017 | Add abstract, authenticated-orcid, fix contributor fields |
 
 ## Work
 
@@ -12,6 +13,7 @@
 |-------|------|----------|-------------|
 | publisher | String | Yes | Name of work's publisher |
 | title | Array of String | Yes | Work titles, including original language title and translated titles |
+| abstract | XML String | No | Abstract as a JSON string or a JATS XML snippet encoded into a JSON string |
 | reference-count | Number | Yes | Count of outbound references deposited with Crossref |
 | source | String | Yes | Currently always `CrossRef` |
 | prefix | URL | Yes | DOI prefix identifier of the form `http://id.crossref.org/prefix/DOI_PREFIX` |
@@ -70,9 +72,10 @@
 
 | Field | Type | Required | Description |
 |-------|------|----------|-------------|
-| family-name | String | Yes | |
-| given-name | String | No | |
+| family | String | Yes | |
+| given | String | No | |
 | ORCID | URL | No | URL-form of an [ORCID](http://orcid.org) identifier |
+| authenticated-orcid | Boolean | No | If true, record owner asserts that the ORCID user completed ORCID OAuth authentication |
 | affiliation | Array of [Affiliation](#affiliation) | No | |
 
 ### Affiliation

From 7cd9ba1d1e2f15789ddbb458d8eae0239abc568c Mon Sep 17 00:00:00 2001
From: Karl Jonathan Ward 
Date: Thu, 27 Jul 2017 10:48:30 +0100
Subject: [PATCH 173/219] Update to cited-by counts alert

---
 README.md | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/README.md b/README.md
index 6d013e8..2b4e177 100644
--- a/README.md
+++ b/README.md
@@ -5,7 +5,7 @@
 
 
 
-- [Service alert: 18 July 2017](#service-alert-18-july-2017)
+- [Service update: 27 July 2017](#service-alert-18-july-2017)
 - [What's new: July 2017](#whats-new-july-2017)
 - [Preamble](#preamble)
 - [Meta](#meta)
@@ -24,9 +24,9 @@
 
 
 
-## Service alert: 18 July 2017
+## Service update: 27 July 2017
 
- Cited-by counts are not updating and should not be considered accurate. We are working on a fix and will update you ([see below](#learning-about-performanceavailability-problems)) when it is in place.
+ Cited-by counts are now up-to-date in the API.
 
 ## What's new: July 2017
 

From 2090b7844947e6df8aee89a73cb3026cd05e1a8b Mon Sep 17 00:00:00 2001
From: Geoffrey Bilder 
Date: Thu, 27 Jul 2017 12:12:51 +0200
Subject: [PATCH 174/219] update toc, document version history

---
 README.md | 17 +----------------
 1 file changed, 1 insertion(+), 16 deletions(-)

diff --git a/README.md b/README.md
index 2b4e177..ec2116e 100644
--- a/README.md
+++ b/README.md
@@ -5,8 +5,6 @@
 
 
 
-- [Service update: 27 July 2017](#service-alert-18-july-2017)
-- [What's new: July 2017](#whats-new-july-2017)
 - [Preamble](#preamble)
 - [Meta](#meta)
 - [API overview](#api-overview)
@@ -24,20 +22,6 @@
 
 
 
-## Service update: 27 July 2017
-
- Cited-by counts are now up-to-date in the API.
-
-## What's new: July 2017
-
-- References are now included if the publisher has made them public.
-- Metadata for preprints, listed as "posted-content"
-- Links from preprints to subsequent publications using "isPreprintOf" relationship
-- Abstracts for over 1 million DOIs
-- Subject categories have been updated to cover more of the content (~45,000 journal titles)
-- "is-referenced-by-count" - also known as cited-by counts.
-
-
 ## Preamble
 
 The Crossref REST API is one of [a variety of tools and APIs](https://www.crossref.org/services/metadata-delivery/) that allow anybody to search and reuse our members' metadata in sophisticated ways.
@@ -638,3 +622,4 @@ Each major version has no backwards incompatible changes within its public inter
 - v49, 2017-07-20, move document version history, add section on libraries
 - v50, 2017-07-20, add TOC, move document history, add etiquet section, add production use section, general formatting + cleanup
 - v51, 2017-07-24, clarified license of the documentation (as opposed to metadata)
+- v52, 2018-07-27, removed service notice and what's new section.

From 744532053908c114583e903e53c65b53e48f013b Mon Sep 17 00:00:00 2001
From: Geoffrey Bilder 
Date: Thu, 27 Jul 2017 12:35:13 +0200
Subject: [PATCH 175/219] re-add notice about cited-by counts

---
 README.md | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/README.md b/README.md
index ec2116e..2902c50 100644
--- a/README.md
+++ b/README.md
@@ -22,6 +22,8 @@
 
 
 
+> Note: Cited-by counts are up-to-date as of 2017-07-27
+
 ## Preamble
 
 The Crossref REST API is one of [a variety of tools and APIs](https://www.crossref.org/services/metadata-delivery/) that allow anybody to search and reuse our members' metadata in sophisticated ways.

From 05fe0087696bb91c57f3d8322f672d1732f52e90 Mon Sep 17 00:00:00 2001
From: Karl Jonathan Ward 
Date: Tue, 8 Aug 2017 10:26:17 +0100
Subject: [PATCH 176/219] Similarity checking resource links

---
 api_format.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/api_format.md b/api_format.md
index a4c0255..f480065 100644
--- a/api_format.md
+++ b/api_format.md
@@ -139,7 +139,7 @@
 
 | Field | Type | Required | Description |
 |-------|------|----------|-------------|
-| intended-application | String | Yes | Either `text-mining` or `unspecified` |
+| intended-application | String | Yes | Either `text-mining`, `similarity-checking` or `unspecified` |
 | content-version | String | Yes | Either `vor` (version of record,) `am` (accepted manuscript) or `unspecified` |
 | URL | URL | Yes | Direct link to a full-text download location |
 | content-type | String | No | Content type (or MIME type) of the full-text object |

From e93f80cc12fb08cad907c6d88cdd94d2e7b2c3fd Mon Sep 17 00:00:00 2001
From: Karl Jonathan Ward 
Date: Tue, 8 Aug 2017 15:18:18 +0100
Subject: [PATCH 177/219] Add many missing fields

With thanks to @henridewinter for detailed information on missing fields.

Fixes CrossRef/rest-api-doc#260
---
 api_format.md | 76 +++++++++++++++++++++++++++++++++++++++++++++++----
 1 file changed, 71 insertions(+), 5 deletions(-)

diff --git a/api_format.md b/api_format.md
index f480065..d467ba7 100644
--- a/api_format.md
+++ b/api_format.md
@@ -12,20 +12,29 @@
 | Field | Type | Required | Description |
 |-------|------|----------|-------------|
 | publisher | String | Yes | Name of work's publisher |
-| title | Array of String | Yes | Work titles, including original language title and translated titles |
+| title | Array of String | Yes | Work titles, including translated titles |
+| original-title | Array of String | No | Work titles in the work's original publication language |
+| short-title | Array of String | No | Short or abbreviated work titles |
 | abstract | XML String | No | Abstract as a JSON string or a JATS XML snippet encoded into a JSON string |
-| reference-count | Number | Yes | Count of outbound references deposited with Crossref |
+| reference-count | Number | Yes | *Deprecated* Same as `references-count` |
+| references-count | Number | Yes | Count of outbound references deposited with Crossref |
+| is-referenced-by-count | Number | Yes | Count of inbound references deposited with Crossref |
 | source | String | Yes | Currently always `CrossRef` |
-| prefix | URL | Yes | DOI prefix identifier of the form `http://id.crossref.org/prefix/DOI_PREFIX` |
+| prefix | String | Yes | DOI prefix identifier of the form `http://id.crossref.org/prefix/DOI_PREFIX` |
 | DOI | String | Yes | DOI of the work |
-| member | URL | Yes | Member identifier of the form `http://id.crossref.org/member/MEMBER_ID` |
+| URL | URL | Yes | URL form of the work's DOI |
+| member | String | Yes | Member identifier of the form `http://id.crossref.org/member/MEMBER_ID` |
 | type | String | Yes | Enumeration, one of the type ids from `https://api.crossref.org/v1/types` |
 | created | [Date](#date) | Yes | Date on which the DOI was first registered |
 | deposited | [Date](#date) | Yes | Date on which the work metadata was most recently updated |
 | indexed | [Date](#date) | Yes | Date on which the work metadata was most recently indexed. Re-indexing does not imply a metadata change, see `deposited` for the most recent metadata change date |
 | issued | [Partial Date](#partial-date) | Yes | Eariest of `published-print` and `published-online` |
+| posted | [Partial Date](#partial-date) | No | Date on which posted content was made available online |
+| accepted | [Partial Date](#partial-date) | No | Date on which a work was accepted, after being submitted, during a submission process |
 | subtitle | Array of String | No | Work subtitles, including original language and translated |
-| container-title | Array of String | No | Titles (full and abbreviated) of the containing work (usually a book or journal.) |
+| container-title | Array of String | No | Full titles of the containing work (usually a book or journal) |
+| short-container-title | Array of String | No | Abbreviated titles of the containing work |
+| group-title | String | No | Group title for posted content |
 | issue | String | No | Issue number of an article's journal |
 | volume | String | No | Volume number of an article's journal |
 | page | String | No | Pages numbers of an article within its journal |
@@ -34,6 +43,7 @@
 | published-online | [Partial Date](#partial-date) | No | Date on which the work was published online |
 | subject | Array of String | No | Subject category names, a controlled vocabulary from Sci-Val. Available for most journal articles |
 | ISSN | Array of String | No | |
+| issn-type | Array of [ISSN with Type](#issn-with-type) | No | List of ISSNs with ISSN type information |
 | ISBN | Array of String | No | |
 | archive | Array of String | No | |
 | license | Array of [License](#license) | No | |
@@ -48,6 +58,10 @@
 | link | Array of [Resource Link](#resource-link) | No | URLs to full-text locations |
 | clinical-trial-number | Array of [Clinical Trial Number](#clinical-trial-number) | No | |
 | alternative-id | String | No | Other identifiers for the work provided by the depositing member |
+| reference | Array of [Reference](#reference) | No | List of references made by the work |
+| content-domain | [Content Domain](#content-domain) | No | Information on domains that support Crossmark for this work |
+| relation | [Relations]#(relations) | No | Relations to other works |
+
 
 ## Work Nested Types
 
@@ -143,3 +157,55 @@
 | content-version | String | Yes | Either `vor` (version of record,) `am` (accepted manuscript) or `unspecified` |
 | URL | URL | Yes | Direct link to a full-text download location |
 | content-type | String | No | Content type (or MIME type) of the full-text object |
+
+### Reference
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| key | String | Yes | |
+| DOI | String | No | |
+| doi-asserted-by | String | No | One of `crossref` or `publisher` |
+| issue | String | No | |
+| first-page | String | No | |
+| volume | String | No | |
+| edition | String | No | |
+| component | String | No | |
+| standard-designator | String | No | |
+| standards-body | String | No | |
+| author | String | No | |
+| year | String | No | |
+| unstructured | String | No | |
+| journal-title | String | No | |
+| article-title | String | No | |
+| series-title | String | No | |
+| volume-title | String | No | |
+| ISSN | String | No | |
+| issn-type | String | No | One of `pissn` or `eissn` |
+| ISBN | String | No | |
+| isbn-type | String | No | |
+
+### ISSN with Type
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| value | String | Yes | |
+| type | String | Yes | One of `eissn`, `pissn` or `lissn` |
+
+### Content Domain
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| domain | Array of String | Yes | |
+| crossmark-restriction | Boolean | Yes | |
+
+### Relations
+
+A hashmap containing relation name, [Relation]#(relation) pairs.
+
+### Relation
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| id-type | String | Yes | |
+| id | String | Yes | |
+| asserted-by | String | Yes | One of `subject` or `object` |

From b19f3546234bd64e42f6c7609a217e902688f3f2 Mon Sep 17 00:00:00 2001
From: Karl Jonathan Ward 
Date: Tue, 8 Aug 2017 15:21:16 +0100
Subject: [PATCH 178/219] Fix some links

---
 api_format.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/api_format.md b/api_format.md
index d467ba7..c3fddc0 100644
--- a/api_format.md
+++ b/api_format.md
@@ -60,7 +60,7 @@
 | alternative-id | String | No | Other identifiers for the work provided by the depositing member |
 | reference | Array of [Reference](#reference) | No | List of references made by the work |
 | content-domain | [Content Domain](#content-domain) | No | Information on domains that support Crossmark for this work |
-| relation | [Relations]#(relations) | No | Relations to other works |
+| relation | [Relations](#relations) | No | Relations to other works |
 
 
 ## Work Nested Types
@@ -200,7 +200,7 @@
 
 ### Relations
 
-A hashmap containing relation name, [Relation]#(relation) pairs.
+A hashmap containing relation name, [Relation](#relation) pairs.
 
 ### Relation
 

From 09dcd50d947b39919ef0a35e49f111b2b4c39ccf Mon Sep 17 00:00:00 2001
From: Karl Jonathan Ward 
Date: Fri, 11 Aug 2017 10:16:24 +0100
Subject: [PATCH 179/219] Mention full-text.application filter

---
 README.md | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/README.md b/README.md
index 2902c50..12e2686 100644
--- a/README.md
+++ b/README.md
@@ -381,6 +381,7 @@ Filters allow you to narrow queries. All filter results are lists.  The followin
 | `has-full-text` |  | metadata that includes any full text `` elements. |
 | `full-text.version` | `{string}`  | metadata where `` element's `content_version` attribute is `{string}`. |
 | `full-text.type` | `{mime_type}`  | metadata where `` element's `content_type` attribute is `{mime_type}` (e.g. `application/pdf`). |
+| `full-text.application` | `{string}` | metadata where `` link has one of the following intended applications: `text-mining`, `similarity-checking` or `unspecified` |
 | `has-references` | | metadata for works that have a list of references |
 | `has-archive` | | metadata which include name of archive partner |
 | `archive` | `{string}` | metadata which where value of archive partner is `{string}` |
@@ -624,4 +625,5 @@ Each major version has no backwards incompatible changes within its public inter
 - v49, 2017-07-20, move document version history, add section on libraries
 - v50, 2017-07-20, add TOC, move document history, add etiquet section, add production use section, general formatting + cleanup
 - v51, 2017-07-24, clarified license of the documentation (as opposed to metadata)
-- v52, 2018-07-27, removed service notice and what's new section.
+- v52, 2017-07-27, removed service notice and what's new section.
+- v53, 2017-08-11, mention `full-text.application` filter

From bfb03448cdcb2d84cedc96e88d63f88ea5caf204 Mon Sep 17 00:00:00 2001
From: Geoffrey Bilder 
Date: Wed, 16 Aug 2017 09:52:27 +0100
Subject: [PATCH 180/219] first checkin of example jupyter notebook

---
 jupyter/crossref-api-demo.ipynb | 1092 +++++++++++++++++++++++++++++++
 1 file changed, 1092 insertions(+)
 create mode 100644 jupyter/crossref-api-demo.ipynb

diff --git a/jupyter/crossref-api-demo.ipynb b/jupyter/crossref-api-demo.ipynb
new file mode 100644
index 0000000..08eb75f
--- /dev/null
+++ b/jupyter/crossref-api-demo.ipynb
@@ -0,0 +1,1092 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "metadata": {
+    "button": false,
+    "new_sheet": false,
+    "run_control": {
+     "read_only": false
+    }
+   },
+   "source": [
+    "## Introduction\n",
+    "\n",
+    "The Crossref REST API is entirely based on URLs and is [documented extensively](https://api.crossref.org). This means, that, in theory, you can simply get all the data that you want using a normal browser. For example, you might want to see the latest DOI records in the Crossref system. You can see this with the following URL:\n",
+    "\n",
+    "[`https://www.crossref.org/works`](https://api.crossref.org/works)\n",
+    "\n",
+    "\n",
+    "This means the REST API is pretty easy to use with basic low level HTTP libraries(e.g. Python's `requests`), but for this tutorial we are going to use a [higher level python library](https://github.com/fabiobatalha/crossrefapi) developed by Fabio Batalha C. Santos at [Scielo](www.scielo.org).\n",
+    "\n",
+    "The examples here are in Python 3. Sorry- but you're going to have to make the move sometime ;)\n",
+    "\n",
+    "To use this librarary you can:\n",
+    "\n",
+    "`pip install crossrefapi`\n",
+    "\n",
+    "Then, import the library and get ready to look at so `works` data. "
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {
+    "button": false,
+    "collapsed": true,
+    "new_sheet": false,
+    "run_control": {
+     "read_only": false
+    }
+   },
+   "outputs": [],
+   "source": [
+    "# If veiwing in pineapple notebook, uncomment the next two lines and then run the cell.\n",
+    "#import pineapple\n",
+    "#%require crossrefapi"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {
+    "button": false,
+    "new_sheet": false,
+    "run_control": {
+     "read_only": false
+    }
+   },
+   "outputs": [],
+   "source": [
+    "# If viewing in jupyter notebook, then uncomment the next line and run the cell.\n",
+    "!pip install crossrefapi"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {
+    "button": false,
+    "collapsed": true,
+    "new_sheet": false,
+    "run_control": {
+     "read_only": false
+    }
+   },
+   "outputs": [],
+   "source": [
+    "from crossref.restful import Works\n",
+    "works = Works()"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {
+    "button": false,
+    "new_sheet": false,
+    "run_control": {
+     "read_only": false
+    }
+   },
+   "source": [
+    "## Working with \"works\"\n",
+    "\n",
+    "Let's start by looking breifly looking at\"works\". The route refers to items identified by a DOI in the index. These can be articles, books, components, etc.\n",
+    "\n",
+    "**TIP:** Crossref does not use \"works\" in the [FRBR](https://en.wikipedia.org/wiki/Functional_Requirements_for_Bibliographic_Records) sense of the word. In Crossref parlance, a \"work\" is just a thing identifed by a DOI. In practice, Crossref DOIs are used as citaton identifiers. So, in FRBR terms, this means, that a Crossref DOI tends to refer to one _expression_ which might include multiple _manifestations_. So, for example, the ePub, HTML and PDF version of an article will share a Crossref DOI because the differences between them should not effect the interpretation or crediting of the content. In short, they can be cited interchangeabley. The same is true of the \"accepted manuscript\" and the \"version-of-record\" of that accepted manuscript.\n",
+    "\n",
+    "In order to start querying information about works, we need to import the library and make things convenient."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 3,
+   "metadata": {
+    "button": false,
+    "collapsed": true,
+    "new_sheet": false,
+    "run_control": {
+     "read_only": false
+    }
+   },
+   "outputs": [],
+   "source": [
+    "from crossref.restful import Works\n",
+    "works = Works()"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {
+    "button": false,
+    "new_sheet": false,
+    "run_control": {
+     "read_only": false
+    }
+   },
+   "source": [
+    "Now we are ready to ask our first question- How many Crossref DOI records are indexed by the API?"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 4,
+   "metadata": {
+    "button": false,
+    "new_sheet": false,
+    "run_control": {
+     "read_only": false
+    }
+   },
+   "outputs": [
+    {
+     "data": {
+      "text/plain": [
+       "90760017"
+      ]
+     },
+     "execution_count": 4,
+     "metadata": {},
+     "output_type": "execute_result"
+    }
+   ],
+   "source": [
+    "works.count()"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {
+    "button": false,
+    "new_sheet": false,
+    "run_control": {
+     "read_only": false
+    }
+   },
+   "source": [
+    "Note that above I said \"How many Crossref DOIs\". There are several other [DOI registration agencies](https://www.doi.org/registration_agencies.html). Crossref is by far he largest DOI RA, and the other RAs tend to specialize in orthoganal areas (e.g. Music & Video, Local language translations of publications, etc.) but it is important to not that this API will not work with non-Crossref DOIs (though [DataCite](www.datacite.org], another RA, provides a very similar API).\n",
+    "\n",
+    "**TIP:** Not all DOIs are Crossref DOIs. If you are having trouble using a DOI with Crossref's API, check to see if it is a Crossref DOI.\n",
+    "\n",
+    "So the next obvious question is, how do I tell if a DOI is a Crossref DOI?"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {
+    "button": false,
+    "new_sheet": false,
+    "run_control": {
+     "read_only": false
+    }
+   },
+   "outputs": [],
+   "source": [
+    "works.agency('10.1590/0102-311x00133115')"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {
+    "button": false,
+    "new_sheet": false,
+    "run_control": {
+     "read_only": false
+    }
+   },
+   "outputs": [],
+   "source": [
+    "works.agency('10.6084/m9.figshare.1314859.v1')"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {
+    "button": false,
+    "new_sheet": false,
+    "run_control": {
+     "read_only": false
+    }
+   },
+   "outputs": [],
+   "source": [
+    "works.agency('10.5240/B1FA-0EEC-C316-3316-3A73-L')"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {
+    "button": false,
+    "new_sheet": false,
+    "run_control": {
+     "read_only": false
+    }
+   },
+   "source": [
+    "OK, so assuming that we are using a Crossref DOI, how do we get the metadata for it?"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {
+    "button": false,
+    "new_sheet": false,
+    "run_control": {
+     "read_only": false
+    }
+   },
+   "outputs": [],
+   "source": [
+    "record = works.doi('10.7554/eLife.09561')\n",
+    "record"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {
+    "button": false,
+    "new_sheet": false,
+    "run_control": {
+     "read_only": false
+    }
+   },
+   "source": [
+    "This is bascially a huge JSON object, so you can retreive individual elements from it. Here is the publisher:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {
+    "button": false,
+    "new_sheet": false,
+    "run_control": {
+     "read_only": false
+    }
+   },
+   "outputs": [],
+   "source": [
+    "record['publisher']"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {
+    "button": false,
+    "new_sheet": false,
+    "run_control": {
+     "read_only": false
+    }
+   },
+   "source": [
+    "And here is the license for the \"verson of record\":"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {
+    "button": false,
+    "new_sheet": false,
+    "run_control": {
+     "read_only": false
+    }
+   },
+   "outputs": [],
+   "source": [
+    "next((item for item in record['license'] if item[\"content-version\"] == \"vor\"))['URL']"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {
+    "button": false,
+    "collapsed": true,
+    "new_sheet": false,
+    "run_control": {
+     "read_only": false
+    }
+   },
+   "source": [
+    "Um... That was complicated. What does 'vor' mean?\n",
+    "\n",
+    "**TIP:** Publishers sometimes record information for multiple versions of the content identified by a DOI. These versions should be interchaneable from the point of view of citation, but sometimes one version has more \"features\" than another. For example, it might be typset or have references linked, etc. The two versions might also have different licenses and different URLs. The terminology publishers use for identifying versions comes from the [NISO standard call JAV (Journal Artcle Version)](http://www.niso.org/publications/rp/RP-8-2008.pdf) and, although this terminology is [sometimes problematic](https://f1000research.com/articles/6-608/v1), you should be aware of it. In particualr, you will see two terms used  in Crossref metadata:\n",
+    "\n",
+    "- `VOR` = Version of Record\n",
+    "- `AM` = Accepted Manuscript\n",
+    "\n",
+    "\n",
+    "\n",
+    "Now that we know what 'vor' means, let's get the link to the full text of the version of record:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {
+    "button": false,
+    "new_sheet": false,
+    "run_control": {
+     "read_only": false
+    }
+   },
+   "outputs": [],
+   "source": [
+    "next((item for item in record['link'] if item[\"content-version\"] == \"vor\"))['URL']"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "The above has given us a brief overview of how to get a record and elements of a record identified with a Crossref DOI. Obviously, the goald is to do this in bulk. That is, to select and process records for multiple Crossref DOIs. Before we do that, it is helpful to familiarise yourself with some of the other \"routes\" supported by the REST API. This is because more advanced usage of the API typically involveds combining information from several routes. "
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {
+    "button": false,
+    "collapsed": true,
+    "new_sheet": false,
+    "run_control": {
+     "read_only": false
+    }
+   },
+   "source": [
+    "## Members\n",
+    "\n",
+    "Crossref is a membership organization. DOI records are registered and managed by those members. It is often very useful to break down Crossref DOI records by member. But first let's find out a little bit more about members.\n",
+    "\n",
+    "First we import and setup a useful shortcut. "
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {
+    "button": false,
+    "collapsed": true,
+    "new_sheet": false,
+    "run_control": {
+     "read_only": false
+    }
+   },
+   "outputs": [],
+   "source": [
+    "from crossref.restful import Members\n",
+    "members = Members()"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {
+    "button": false,
+    "new_sheet": false,
+    "run_control": {
+     "read_only": false
+    }
+   },
+   "source": [
+    "How many members does Crossref have?"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {
+    "button": false,
+    "new_sheet": false,
+    "run_control": {
+     "read_only": false
+    }
+   },
+   "outputs": [],
+   "source": [
+    "members.count()"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Let's look at a partciularmember, Hindawi:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {
+    "button": false,
+    "new_sheet": false,
+    "run_control": {
+     "read_only": false
+    }
+   },
+   "outputs": [],
+   "source": [
+    "pub = next(iter(members.query('Hindawi')))\n",
+    "pub"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "**TIP:** Many people make the mistake of thinking that a \"DOI prefix\" can be used to identify the member responsible for a Crossref DOI. This is not true. DOI prefixes merely serve as a namspace form which a member can create new DOIs without worrying about collisions. But, once created, Crossref DOIs are often transfered between publishers and so a Crossref member will often be responsible for DOIs with a variety of prefixes. So, for example, above, Hindawi is responsible for several prefixes:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "prefixes = [p['value'] for p in pub['prefix']]\n",
+    "prefixes"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "**TIP** The most accurate way to refer a particular Crossref member and *all* their prefixes is through the member's `id`.\n",
+    "\n",
+    "So let's look at eLife."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "pub = next(iter(members.query('eLife')))\n",
+    "pub"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {
+    "button": false,
+    "new_sheet": false,
+    "run_control": {
+     "read_only": false
+    }
+   },
+   "source": [
+    "eLife's Crossref member ID can be accessed as follows:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {
+    "button": false,
+    "new_sheet": false,
+    "run_control": {
+     "read_only": false
+    }
+   },
+   "outputs": [],
+   "source": [
+    "pub_id = pub['id']\n",
+    "pub_id"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {
+    "button": false,
+    "collapsed": true,
+    "new_sheet": false,
+    "run_control": {
+     "read_only": false
+    }
+   },
+   "source": [
+    "Now we can use this ID to specifically refer to eLife. For example:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {
+    "button": false,
+    "new_sheet": false,
+    "run_control": {
+     "read_only": false
+    }
+   },
+   "outputs": [],
+   "source": [
+    "pub = members.member(pub_id)\n",
+    "pub"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {
+    "button": false,
+    "new_sheet": false,
+    "run_control": {
+     "read_only": false
+    }
+   },
+   "source": [
+    "Let's see how many DOIs eLife has registered by year:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {
+    "button": false,
+    "new_sheet": false,
+    "run_control": {
+     "read_only": false
+    }
+   },
+   "outputs": [],
+   "source": [
+    "dois_by_year = pub['breakdowns']['dois-by-issued-year']\n",
+    "dois_by_year"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {
+    "button": false,
+    "new_sheet": false,
+    "run_control": {
+     "read_only": false
+    }
+   },
+   "source": [
+    "Cool, now let's look at some of the publisher data in more friendly formats. We are going to use the pandas library for summarising and visualising the data."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {
+    "button": false,
+    "collapsed": true,
+    "new_sheet": false,
+    "run_control": {
+     "read_only": false
+    }
+   },
+   "outputs": [],
+   "source": [
+    "import pandas as pd\n",
+    "%matplotlib inline"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {
+    "button": false,
+    "new_sheet": false,
+    "run_control": {
+     "read_only": false
+    }
+   },
+   "source": [
+    "First let's see the publications by year in a nice, sorted table:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {
+    "button": false,
+    "new_sheet": false,
+    "run_control": {
+     "read_only": false
+    }
+   },
+   "outputs": [],
+   "source": [
+    "f = pd.DataFrame(dois_by_year)\n",
+    "f.columns = ['year','dois']\n",
+    "dois_sorted_by_year = f.sort_values(['year','dois'])\n",
+    "dois_sorted_by_year"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {
+    "button": false,
+    "new_sheet": false,
+    "run_control": {
+     "read_only": false
+    }
+   },
+   "source": [
+    "Maybe look at this in a graph?"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {
+    "button": false,
+    "new_sheet": false,
+    "run_control": {
+     "read_only": false
+    }
+   },
+   "outputs": [],
+   "source": [
+    "dois_sorted_by_year.plot.bar(x='year',y='dois')"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {
+    "button": false,
+    "new_sheet": false,
+    "run_control": {
+     "read_only": false
+    }
+   },
+   "source": [
+    "We can pull this all together and you can look at a number of publishers. Try changing the publisher name in the code below to something else:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {
+    "button": false,
+    "new_sheet": false,
+    "run_control": {
+     "read_only": false
+    }
+   },
+   "outputs": [],
+   "source": [
+    "publisher_name = 'PLOS'\n",
+    "pub_id = next(iter(members.query(publisher_name)))['id']\n",
+    "pub = members.member(pub_id)\n",
+    "dois_by_year = pub['breakdowns']['dois-by-issued-year']\n",
+    "f = pd.DataFrame(dois_by_year)\n",
+    "f.columns = ['year','dois']\n",
+    "dois_sorted_by_year = f.sort_values(['year','dois'])\n",
+    "dois_sorted_by_year.plot.bar(x='year',y='dois',figsize=(50, 7))"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {
+    "button": false,
+    "new_sheet": false,
+    "run_control": {
+     "read_only": false
+    }
+   },
+   "source": [
+    "A publisher record also contains a useful summary of the member's metadata and the Crossref services that they particpate in.\n",
+    "\n",
+    "Let's look at what percentage of their metadata includes certain information:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {
+    "button": false,
+    "new_sheet": false,
+    "run_control": {
+     "read_only": false
+    }
+   },
+   "outputs": [],
+   "source": [
+    "coverage = [[key,float(pub['coverage'][key])*100] for key in pub['coverage'].keys()]\n",
+    "coverage"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {
+    "button": false,
+    "new_sheet": false,
+    "run_control": {
+     "read_only": false
+    }
+   },
+   "outputs": [],
+   "source": [
+    "f = pd.DataFrame(coverage)\n",
+    "f.columns = ['metadata','coverage']\n",
+    "f.plot.barh(x='metadata',y='coverage')"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {
+    "button": false,
+    "new_sheet": false,
+    "run_control": {
+     "read_only": false
+    }
+   },
+   "source": [
+    "Now let's see what Crossref services they particpate in:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {
+    "button": false,
+    "new_sheet": false,
+    "run_control": {
+     "read_only": false
+    }
+   },
+   "outputs": [],
+   "source": [
+    "particpation = [[key,pub['flags'][key]] for key in pub['flags'].keys()]\n",
+    "f = pd.DataFrame(particpation)\n",
+    "f.columns = ['service','paticipation']\n",
+    "f"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Fun with facets\n",
+    "\n",
+    "### Orchid support"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "from crossref.restful import Works\n",
+    "works = Works()\n",
+    "r = works.filter(has_orcid='true').facet('publisher-name',10)\n",
+    "orcid_support = [[key,r['publisher-name']['values'][key]] for key in r['publisher-name']['values'].keys()]\n",
+    "f = pd.DataFrame(orcid_support)\n",
+    "f.columns = ['publisher','orcids']\n",
+    "f.plot.barh(x='publisher',y='orcids')"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Zika publications"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "r = works.query(title='Zika').facet('publisher-name',10)\n",
+    "zika_publications = [[key,r['publisher-name']['values'][key]] for key in r['publisher-name']['values'].keys()]\n",
+    "f = pd.DataFrame(zika_publications)\n",
+    "f.columns = ['publisher','publications']\n",
+    "f.plot.barh(x='publisher',y='publications')"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Some outher resources\n",
+    "\n",
+    "### Types"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "from crossref.restful import Types\n",
+    "types = [type['label'] for type in Types().all()]\n",
+    "types.sort()\n",
+    "types"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {
+    "collapsed": true
+   },
+   "outputs": [],
+   "source": []
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "### Journals"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "from crossref.restful import Journals\n",
+    "journals = Journals()\n",
+    "journals.count()\n"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "journal = journals.journal('0028-0836')\n",
+    "journal"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## A slight digression to discuss testing debugging queries\n",
+    "\n",
+    "**TIP** One of the cool things about the library we are using, is that you can easily see the REST API URIs that it generates for queries you make to the API. To do this, you simply ask for the URL of the query in question. So, for example- if you want to see the API call for the code we used for asking for the number of Crossref DOIs."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "from crossref.restful import Works\n",
+    "works = Works()\n",
+    "zika_sample = [work for work in works.query('zika').sample(10)]\n",
+    "zika_sample"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Using samples for testing and to save time"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {
+    "collapsed": true
+   },
+   "outputs": [],
+   "source": [
+    "from crossref.restful import Works\n",
+    "works = Works()\n",
+    "works.query('zika').url"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {
+    "button": false,
+    "collapsed": true,
+    "new_sheet": false,
+    "run_control": {
+     "read_only": false
+    }
+   },
+   "source": [
+    "## Some Jisc Examples\n",
+    "\n",
+    "### Notify institutions of co-authored works"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {
+    "button": false,
+    "new_sheet": false,
+    "run_control": {
+     "read_only": false
+    }
+   },
+   "source": [
+    "Works records indexed _today_ that have affiliatioon data"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {
+    "button": false,
+    "new_sheet": false,
+    "run_control": {
+     "read_only": false
+    }
+   },
+   "outputs": [],
+   "source": [
+    "import datetime\n",
+    "works=Works()\n",
+    "today = datetime.date.today().isoformat()\n",
+    "works_with_affiliations = [w for w in works.filter(from_online_pub_date=today, has_affiliation='true')]\n",
+    "print(len(works_with_affiliations))\n"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Let's look for publications with a publication date of today and a particular affiliation."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {
+    "button": false,
+    "new_sheet": false,
+    "run_control": {
+     "read_only": false
+    }
+   },
+   "outputs": [],
+   "source": [
+    "import datetime\n",
+    "affiliation=\"Harvard\"\n",
+    "today = datetime.date.today().isoformat()\n",
+    "recent_affiliation_pubs = works.filter(from_online_pub_date=today).query(affiliation=affiliation)\n",
+    "recent_affiliation_pubs.count()"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Let's look at the first record..."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {
+    "button": false,
+    "new_sheet": false,
+    "run_control": {
+     "read_only": false
+    }
+   },
+   "outputs": [],
+   "source": [
+    "next(iter(recent_affiliation_pubs))"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {
+    "button": false,
+    "collapsed": true,
+    "new_sheet": false,
+    "run_control": {
+     "read_only": false
+    }
+   },
+   "source": [
+    "#### A digression on organizational identifiers...\n"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "### Integrate funding data into funder policy service"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {
+    "collapsed": true
+   },
+   "outputs": [],
+   "source": [
+    "from crossref.restful import Funders\n",
+    "funders=Funders()\n",
+    "funder_name=\"NIH\"\n",
+    "funder_id=next(iter(funders.query(funder_name)))['id']\n",
+    "funder_id"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {
+    "collapsed": true
+   },
+   "outputs": [],
+   "source": [
+    "import datetime\n",
+    "works=Works()\n",
+    "today = datetime.date.today().isoformat()\n",
+    "works_with_funding_data = [w for w in works.filter(from_online_pub_date='2017-01-01', funder=funder_id)]\n",
+    "print(len(works_with_funding_data))"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {
+    "collapsed": true
+   },
+   "outputs": [],
+   "source": [
+    "next(iter(works_with_funding_data))"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "### "
+   ]
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "Python 3",
+   "language": "python",
+   "name": "python3"
+  },
+  "language_info": {
+   "codemirror_mode": {
+    "name": "ipython",
+    "version": 3
+   },
+   "file_extension": ".py",
+   "mimetype": "text/x-python",
+   "name": "python",
+   "nbconvert_exporter": "python",
+   "pygments_lexer": "ipython3",
+   "version": "3.6.1"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 2
+}

From 597d4b0c2b8d2190d34dcb209cf677434969005a Mon Sep 17 00:00:00 2001
From: jenniferlin15 
Date: Sat, 2 Sep 2017 11:20:39 -0700
Subject: [PATCH 181/219] correct Crossref capitalisation typos

---
 README.md     | 14 +++++++-------
 api_format.md |  2 +-
 2 files changed, 8 insertions(+), 8 deletions(-)

diff --git a/README.md b/README.md
index 12e2686..c5b0b45 100644
--- a/README.md
+++ b/README.md
@@ -32,7 +32,7 @@ The Crossref REST API is one of [a variety of tools and APIs](https://www.crossr
 ## Meta
 ### Learning about performance or availability problems
 
-Note that we generally post notice any ongoing performance problems with our services on our twitter feeds at [CrossRefOrg](https://twitter.com/CrossrefOrg) and [CrossRefSupport](https://twitter.com/@CrossrefSupport). We also report them on our [support site](https://support.crossref.org/hc/en-us). You might want to check these to see if we are already aware of a problem before you report it.
+Note that we generally post notice any ongoing performance problems with our services on our twitter feeds at [CrossrefOrg](https://twitter.com/CrossrefOrg) and [CrossrefSupport](https://twitter.com/@CrossrefSupport). We also report them on our [support site](https://support.crossref.org/hc/en-us). You might want to check these to see if we are already aware of a problem before you report it.
 
 ### Reporting performance or availability problems
 
@@ -40,7 +40,7 @@ Report performance/availability at our [support site](https://support.crossref.o
 
 ### Reporting bugs, requesting features ###
 
-Please report bugs with the API or the documentation on our [issue tracker](https://github.com/CrossRef/rest-api-doc/issues).
+Please report bugs with the API or the documentation on our [issue tracker](https://github.com/Crossref/rest-api-doc/issues).
 
 ### Documentation License
 
@@ -63,7 +63,7 @@ You might be able to avoid reading all this documentation if you instead use one
 - [rcrossref](https://github.com/ropensci/rcrossref) (R)
 - [crossrefapi](https://github.com/fabiobatalha/crossrefapi) (Python)
 
-If you know of another library you would like to see listed here, please let us know about it via the [issue tracker](https://github.com/CrossRef/rest-api-doc/issues).
+If you know of another library you would like to see listed here, please let us know about it via the [issue tracker](https://github.com/Crossref/rest-api-doc/issues).
 
 ### Etiquette
 
@@ -76,7 +76,7 @@ We want to provide a public, open,  and free API for all. And we don't want to u
 
 This way we can contact you if we see a problem.
 
-- report problems and/or ask questions on our [issue tracker](https://github.com/CrossRef/rest-api-doc/issues).
+- report problems and/or ask questions on our [issue tracker](https://github.com/Crossref/rest-api-doc/issues).
 
 Alas, not all people are polite. And for this reason we reserve the right to impose rate limits and/or to block clients that are disrupting the public service.
 
@@ -96,7 +96,7 @@ What if you want to use our API for a production service that cannot depend on t
 
 ## API overview
 
-The API is generally RESTFUL and returns results in JSON. JSON formats returned by the API are documented [here](https://github.com/CrossRef/rest-api-doc/blob/master/api_format.md).
+The API is generally RESTFUL and returns results in JSON. JSON formats returned by the API are documented [here](https://github.com/Crossref/rest-api-doc/blob/master/api_format.md).
 
 The API supports HTTP and HTTPS. Examples here are provided using HTTPS.
 
@@ -203,7 +203,7 @@ These can be used alone like this
 | resource      | description                       |
 |:--------------|:----------------------------------|
 | `/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 [Funder Registry](https://github.com/CrossRef/open-funder-registry)
+| `/funders`    | returns a list of all funders in the [Funder Registry](https://github.com/Crossref/open-funder-registry)
 | `/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 |
@@ -355,7 +355,7 @@ Filters allow you to narrow queries. All filter results are lists.  The followin
 | `funder` | `{funder_id}` | metadata which include the `{funder_id}` in FundRef data |
 | `location` |`{country_name}` | funder records where location = `{country name}`. Only works on `/funders` route |
 | `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}` |
diff --git a/api_format.md b/api_format.md
index c3fddc0..026caa4 100644
--- a/api_format.md
+++ b/api_format.md
@@ -19,7 +19,7 @@
 | reference-count | Number | Yes | *Deprecated* Same as `references-count` |
 | references-count | Number | Yes | Count of outbound references deposited with Crossref |
 | is-referenced-by-count | Number | Yes | Count of inbound references deposited with Crossref |
-| source | String | Yes | Currently always `CrossRef` |
+| source | String | Yes | Currently always `Crossref` |
 | prefix | String | Yes | DOI prefix identifier of the form `http://id.crossref.org/prefix/DOI_PREFIX` |
 | DOI | String | Yes | DOI of the work |
 | URL | URL | Yes | URL form of the work's DOI |

From d5dc2c7c7e2dee6099493fa476cc6f89f6e00a12 Mon Sep 17 00:00:00 2001
From: jenniferlin15 
Date: Sat, 2 Sep 2017 11:28:19 -0700
Subject: [PATCH 182/219] one last capitalization typo for Crossref

---
 README.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/README.md b/README.md
index c5b0b45..e19a1f1 100644
--- a/README.md
+++ b/README.md
@@ -126,7 +126,7 @@ Will return the following result:
         DOI: "10.1037/0003-066x.59.1.29",
         agency: {
           id: "crossref",
-          label: "CrossRef"
+          label: "Crossref"
         }
       }
     }

From d2e80579c94b4d9c9d1ba342e98ef492379207cb Mon Sep 17 00:00:00 2001
From: Geoffrey Bilder 
Date: Tue, 19 Sep 2017 17:43:43 +0200
Subject: [PATCH 183/219] add info about polite pool

---
 README.md | 40 ++++++++++++++++++++++++++++++++++++++--
 1 file changed, 38 insertions(+), 2 deletions(-)

diff --git a/README.md b/README.md
index e19a1f1..0e07529 100644
--- a/README.md
+++ b/README.md
@@ -67,11 +67,11 @@ If you know of another library you would like to see listed here, please let us
 
 ### Etiquette
 
-We want to provide a public, open,  and free API for all. And we don't want to unnecessarily burden developers (or ourselves) with cumbersome API tokens or registration processes in order to use the public REST API. For that to work, we ask that you be polite and try not to do anything that will take the public REST API down or otherwise make it unusable for others. Specifically, we encourage the following polite behaviour:
+We want to provide a public, open, and free API for all. And we don't want to unnecessarily burden developers (or ourselves) with cumbersome API tokens or registration processes in order to use the public REST API. For that to work, we ask that you be polite and try not to do anything that will take the public REST API down or otherwise make it unusable for others. Specifically, we encourage the following polite behaviour:
 
 - Cache data so you don't request the same data over and over again. 
 - Actively monitor API response times. If they start to go up, back-off for a while. For example, add pauses between requests and/or reduce the number of parallel requests.
-- Specify a `User-Agent` header that properly identifies your script or tool and that provides some type of means of contacting you. For example:
+- Specify a `User-Agent` header that properly identifies your script or tool and that provides a means of contacting you vai email using "mailto:". For example:
 `GroovyBib/1.1 (https://example.org/GroovyBib/; mailto:GroovyBib@example.org) BasedOnFunkyLib/1.4`.
 
 This way we can contact you if we see a problem.
@@ -80,6 +80,41 @@ This way we can contact you if we see a problem.
 
 Alas, not all people are polite. And for this reason we reserve the right to impose rate limits and/or to block clients that are disrupting the public service.
 
+### Good manners = faster service.
+
+But we prefer carrots to sticks. As of September 18th 2017 any API queries that **use HTTPS and have appropriate contact information** will be directed to a special pool of API machines that are reserved for polite users. Why are are we doing this? Well- we don't want to force users to have to register with us. But this means that if some user of the public server writes a buggy script or ignores timeouts and errors- they can really bring the API service to its knees. Whats more, it is very hard for us to identify these problem users because they tend to work off multiple parallel machines and use generic User-Agent headers. They are effectively anonymous. We're starting to have to spend a lot of time dealing with these problems and the degraded pefromance of the public API is affecting all the polite users as well.
+
+So... we are keeping the public service as is. It will probably continue to flutuate widely in performance. But now, if a client connects to the API using HTTPS and provides contact information either in their User-Agent header or as a parameter on their queries, then we will send them to a separate pool of machines. We expect to be able to better control the performance of these machines because, if a script starts causing problems, we can contact the people repsonsible for the script to ask them to fix it. Or, in extremis, we can block it.
+
+How does it work? Simple. You can do one of two things to get directed to the "polite pool":
+
+1) Include a "mailto" parameter in your query. For example:
+
+`http://api.crossref.org/works?filter=has-full-text:true&mailto=GroovyBib@example.org` 
+
+2) Include a "mailto:" in your User-Agent header. For example:
+
+`GroovyBib/1.1 (https://example.org/GroovyBib/; mailto:GroovyBib@example.org) BasedOnFunkyLib/1.4`.
+
+Note that this only works if you query the API using HTTPS. You really should be doing that anyway (wags finger).
+
+#### Frequently anticpated questions
+
+**Q:** Will you spam me with marketing bumpf once you have our contact info?
+**A:** No. We will only use it to contact you about problems with your scripts.
+
+**Q:** Is this a secret plot to kill public access to your API?
+**A:** No. It is an attempt to keep a public API reliable.
+
+**Q:** What if I provide fake or incorrect contact info?
+**A:** That is not very polite. If there is a problem and you don't repond, we'll block you.
+
+**Q:** Does the contact info have to be a real name?
+**A:** No. As long as somebody actually recieves and pays attention to email at the address, it can be pseudoanonymous, or whatever.
+
+
+
+
 #### Rate limits
 
 From time to time Crossref needs to impose rate limits to ensure that the free API is usable by all. Any rate limits that are in effect will be advertised in the `X-Rate-Limit-Limit` and `X-Rate-Limit-Interval` HTTP headers.
@@ -627,3 +662,4 @@ Each major version has no backwards incompatible changes within its public inter
 - v51, 2017-07-24, clarified license of the documentation (as opposed to metadata)
 - v52, 2017-07-27, removed service notice and what's new section.
 - v53, 2017-08-11, mention `full-text.application` filter
+- v54, 2017-09-18, add info about new "polite pool"

From 3497fa7ccb43ccf809fe9f5233e91082616a6664 Mon Sep 17 00:00:00 2001
From: Geoffrey Bilder 
Date: Tue, 19 Sep 2017 17:45:23 +0200
Subject: [PATCH 184/219] formatting

---
 README.md | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/README.md b/README.md
index 0e07529..d5b7ba4 100644
--- a/README.md
+++ b/README.md
@@ -82,7 +82,9 @@ Alas, not all people are polite. And for this reason we reserve the right to imp
 
 ### Good manners = faster service.
 
-But we prefer carrots to sticks. As of September 18th 2017 any API queries that **use HTTPS and have appropriate contact information** will be directed to a special pool of API machines that are reserved for polite users. Why are are we doing this? Well- we don't want to force users to have to register with us. But this means that if some user of the public server writes a buggy script or ignores timeouts and errors- they can really bring the API service to its knees. Whats more, it is very hard for us to identify these problem users because they tend to work off multiple parallel machines and use generic User-Agent headers. They are effectively anonymous. We're starting to have to spend a lot of time dealing with these problems and the degraded pefromance of the public API is affecting all the polite users as well.
+But we prefer carrots to sticks. As of September 18th 2017 any API queries that **use HTTPS and have appropriate contact information** will be directed to a special pool of API machines that are reserved for polite users.
+
+Why are are we doing this? Well- we don't want to force users to have to register with us. But this means that if some user of the public server writes a buggy script or ignores timeouts and errors- they can really bring the API service to its knees. Whats more, it is very hard for us to identify these problem users because they tend to work off multiple parallel machines and use generic User-Agent headers. They are effectively anonymous. We're starting to have to spend a lot of time dealing with these problems and the degraded pefromance of the public API is affecting all the polite users as well.
 
 So... we are keeping the public service as is. It will probably continue to flutuate widely in performance. But now, if a client connects to the API using HTTPS and provides contact information either in their User-Agent header or as a parameter on their queries, then we will send them to a separate pool of machines. We expect to be able to better control the performance of these machines because, if a script starts causing problems, we can contact the people repsonsible for the script to ask them to fix it. Or, in extremis, we can block it.
 

From 1a0068897460f40e56a997ff15581f433830cb46 Mon Sep 17 00:00:00 2001
From: Geoffrey Bilder 
Date: Tue, 19 Sep 2017 18:01:18 +0200
Subject: [PATCH 185/219] https

---
 README.md | 9 ++++++++-
 1 file changed, 8 insertions(+), 1 deletion(-)

diff --git a/README.md b/README.md
index d5b7ba4..ca198ea 100644
--- a/README.md
+++ b/README.md
@@ -92,7 +92,7 @@ How does it work? Simple. You can do one of two things to get directed to the "p
 
 1) Include a "mailto" parameter in your query. For example:
 
-`http://api.crossref.org/works?filter=has-full-text:true&mailto=GroovyBib@example.org` 
+`https://api.crossref.org/works?filter=has-full-text:true&mailto=GroovyBib@example.org` 
 
 2) Include a "mailto:" in your User-Agent header. For example:
 
@@ -103,15 +103,22 @@ Note that this only works if you query the API using HTTPS. You really should be
 #### Frequently anticpated questions
 
 **Q:** Will you spam me with marketing bumpf once you have our contact info?
+
 **A:** No. We will only use it to contact you about problems with your scripts.
 
+
 **Q:** Is this a secret plot to kill public access to your API?
+
 **A:** No. It is an attempt to keep a public API reliable.
 
+
 **Q:** What if I provide fake or incorrect contact info?
+
 **A:** That is not very polite. If there is a problem and you don't repond, we'll block you.
 
+
 **Q:** Does the contact info have to be a real name?
+
 **A:** No. As long as somebody actually recieves and pays attention to email at the address, it can be pseudoanonymous, or whatever.
 
 

From b2167dc1d3cc89632750e665f85a66e2bcdfc0a6 Mon Sep 17 00:00:00 2001
From: Geoffrey Bilder 
Date: Tue, 19 Sep 2017 18:03:29 +0200
Subject: [PATCH 186/219] header fix

---
 README.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/README.md b/README.md
index ca198ea..5034d08 100644
--- a/README.md
+++ b/README.md
@@ -100,7 +100,7 @@ How does it work? Simple. You can do one of two things to get directed to the "p
 
 Note that this only works if you query the API using HTTPS. You really should be doing that anyway (wags finger).
 
-#### Frequently anticpated questions
+##### Frequently anticpated questions
 
 **Q:** Will you spam me with marketing bumpf once you have our contact info?
 
@@ -109,7 +109,7 @@ Note that this only works if you query the API using HTTPS. You really should be
 
 **Q:** Is this a secret plot to kill public access to your API?
 
-**A:** No. It is an attempt to keep a public API reliable.
+**A:** No. It is an attempt to keep the public API reliable.
 
 
 **Q:** What if I provide fake or incorrect contact info?

From 288a1eefb1d2a64859828646814afc4f36a692bb Mon Sep 17 00:00:00 2001
From: Geoffrey Bilder 
Date: Tue, 19 Sep 2017 18:06:28 +0200
Subject: [PATCH 187/219] spelin

---
 README.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/README.md b/README.md
index 5034d08..b82f737 100644
--- a/README.md
+++ b/README.md
@@ -86,7 +86,7 @@ But we prefer carrots to sticks. As of September 18th 2017 any API queries that
 
 Why are are we doing this? Well- we don't want to force users to have to register with us. But this means that if some user of the public server writes a buggy script or ignores timeouts and errors- they can really bring the API service to its knees. Whats more, it is very hard for us to identify these problem users because they tend to work off multiple parallel machines and use generic User-Agent headers. They are effectively anonymous. We're starting to have to spend a lot of time dealing with these problems and the degraded pefromance of the public API is affecting all the polite users as well.
 
-So... we are keeping the public service as is. It will probably continue to flutuate widely in performance. But now, if a client connects to the API using HTTPS and provides contact information either in their User-Agent header or as a parameter on their queries, then we will send them to a separate pool of machines. We expect to be able to better control the performance of these machines because, if a script starts causing problems, we can contact the people repsonsible for the script to ask them to fix it. Or, in extremis, we can block it.
+So... we are keeping the public service as is. It will probably continue to fluctuate widely in performance. But now, if a client connects to the API using HTTPS and provides contact information either in their User-Agent header or as a parameter on their queries, then we will send them to a separate pool of machines. We expect to be able to better control the performance of these machines because, if a script starts causing problems, we can contact the people repsonsible for the script to ask them to fix it. Or, in extremis, we can block it.
 
 How does it work? Simple. You can do one of two things to get directed to the "polite pool":
 
@@ -114,7 +114,7 @@ Note that this only works if you query the API using HTTPS. You really should be
 
 **Q:** What if I provide fake or incorrect contact info?
 
-**A:** That is not very polite. If there is a problem and you don't repond, we'll block you.
+**A:** That is not very polite. If there is a problem and you don't respond, we'll block you.
 
 
 **Q:** Does the contact info have to be a real name?

From 1b0a23982fc82155822e573fc42e53def7d5951c Mon Sep 17 00:00:00 2001
From: Geoffrey Bilder 
Date: Tue, 19 Sep 2017 18:16:04 +0200
Subject: [PATCH 188/219] punctuation

---
 README.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/README.md b/README.md
index b82f737..4f703d0 100644
--- a/README.md
+++ b/README.md
@@ -84,7 +84,7 @@ Alas, not all people are polite. And for this reason we reserve the right to imp
 
 But we prefer carrots to sticks. As of September 18th 2017 any API queries that **use HTTPS and have appropriate contact information** will be directed to a special pool of API machines that are reserved for polite users.
 
-Why are are we doing this? Well- we don't want to force users to have to register with us. But this means that if some user of the public server writes a buggy script or ignores timeouts and errors- they can really bring the API service to its knees. Whats more, it is very hard for us to identify these problem users because they tend to work off multiple parallel machines and use generic User-Agent headers. They are effectively anonymous. We're starting to have to spend a lot of time dealing with these problems and the degraded pefromance of the public API is affecting all the polite users as well.
+Why are are we doing this? Well- we don't want to force users to have to register with us. But this means that if some user of the public server writes a buggy script or ignores timeouts and errors- they can really bring the API service to its knees. What's more, it is very hard for us to identify these problem users because they tend to work off multiple parallel machines and use generic User-Agent headers. They are effectively anonymous. We're starting to have to spend a lot of time dealing with these problems and the degraded pefromance of the public API is affecting all the polite users as well.
 
 So... we are keeping the public service as is. It will probably continue to fluctuate widely in performance. But now, if a client connects to the API using HTTPS and provides contact information either in their User-Agent header or as a parameter on their queries, then we will send them to a separate pool of machines. We expect to be able to better control the performance of these machines because, if a script starts causing problems, we can contact the people repsonsible for the script to ask them to fix it. Or, in extremis, we can block it.
 

From 27fc2f39b759749a75e798bdcc290b676e3064ad Mon Sep 17 00:00:00 2001
From: Geoffrey Bilder 
Date: Tue, 19 Sep 2017 18:21:36 +0200
Subject: [PATCH 189/219] define bumf

---
 README.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/README.md b/README.md
index 4f703d0..218f6fd 100644
--- a/README.md
+++ b/README.md
@@ -102,7 +102,7 @@ Note that this only works if you query the API using HTTPS. You really should be
 
 ##### Frequently anticpated questions
 
-**Q:** Will you spam me with marketing bumpf once you have our contact info?
+**Q:** Will you spam me with marketing [bumf](https://en.oxforddictionaries.com/definition/bumf) once you have our contact info?
 
 **A:** No. We will only use it to contact you about problems with your scripts.
 

From db28e6db1cbd0c89d7a2cfb8c888123877ac13bd Mon Sep 17 00:00:00 2001
From: Geoffrey Bilder 
Date: Tue, 19 Sep 2017 18:35:27 +0200
Subject: [PATCH 190/219] spleling

---
 README.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/README.md b/README.md
index 218f6fd..2848d24 100644
--- a/README.md
+++ b/README.md
@@ -84,7 +84,7 @@ Alas, not all people are polite. And for this reason we reserve the right to imp
 
 But we prefer carrots to sticks. As of September 18th 2017 any API queries that **use HTTPS and have appropriate contact information** will be directed to a special pool of API machines that are reserved for polite users.
 
-Why are are we doing this? Well- we don't want to force users to have to register with us. But this means that if some user of the public server writes a buggy script or ignores timeouts and errors- they can really bring the API service to its knees. What's more, it is very hard for us to identify these problem users because they tend to work off multiple parallel machines and use generic User-Agent headers. They are effectively anonymous. We're starting to have to spend a lot of time dealing with these problems and the degraded pefromance of the public API is affecting all the polite users as well.
+Why are are we doing this? Well- we don't want to force users to have to register with us. But this means that if some user of the public server writes a buggy script or ignores timeouts and errors- they can really bring the API service to its knees. What's more, it is very hard for us to identify these problem users because they tend to work off multiple parallel machines and use generic User-Agent headers. They are effectively anonymous. We're starting to have to spend a lot of time dealing with these problems and the degraded performance of the public API is affecting all the polite users as well.
 
 So... we are keeping the public service as is. It will probably continue to fluctuate widely in performance. But now, if a client connects to the API using HTTPS and provides contact information either in their User-Agent header or as a parameter on their queries, then we will send them to a separate pool of machines. We expect to be able to better control the performance of these machines because, if a script starts causing problems, we can contact the people repsonsible for the script to ask them to fix it. Or, in extremis, we can block it.
 

From b5c9dbbab7c2a5d2f351e8106bf10d94a8a39315 Mon Sep 17 00:00:00 2001
From: Geoffrey Bilder 
Date: Thu, 21 Sep 2017 09:17:38 +0200
Subject: [PATCH 191/219] spelling, new TOC

---
 README.md | 121 ++++++++++++++++++++++++++----------------------------
 1 file changed, 59 insertions(+), 62 deletions(-)

diff --git a/README.md b/README.md
index 2848d24..2524366 100644
--- a/README.md
+++ b/README.md
@@ -1,28 +1,26 @@
 # Crossref REST API
 
-
-
-
-
-
-- [Preamble](#preamble)
-- [Meta](#meta)
-- [API overview](#api-overview)
-- [Result types](#result-types)
-- [Resource components](#resource-components)
-- [Parameters](#parameters)
-- [Queries](#queries)
-- [Field Queries](#field-queries)
-- [Sorting](#sorting)
-- [Facet counts](#facet-counts)
-- [Filter names](#filter-names)
-- [Result controls](#result-controls)
-- [API versioning](#api-versioning)
-- [Documentation history](#documentation-history)
-
-
-
-> Note: Cited-by counts are up-to-date as of 2017-07-27
+
+
+- [Crossref REST API](#crossref-rest-api)
+	- [Preamble](#preamble)
+	- [Meta](#meta)
+	- [API overview](#api-overview)
+	- [Result types](#result-types)
+	- [Resource components](#resource-components)
+	- [Parameters](#parameters)
+	- [Queries](#queries)
+	- [Field Queries](#field-queries)
+	- [Sorting](#sorting)
+	- [Facet counts](#facet-counts)
+	- [Filter names](#filter-names)
+	- [Result controls](#result-controls)
+	- [API versioning](#api-versioning)
+	- [Documentation history](#documentation-history)
+
+
+
+
 
 ## Preamble
 
@@ -38,7 +36,7 @@ Note that we generally post notice any ongoing performance problems with our ser
 
 Report performance/availability at our [support site](https://support.crossref.org/hc/en-us).
 
-### Reporting bugs, requesting features ###
+### Reporting bugs, requesting features
 
 Please report bugs with the API or the documentation on our [issue tracker](https://github.com/Crossref/rest-api-doc/issues).
 
@@ -69,7 +67,7 @@ If you know of another library you would like to see listed here, please let us
 
 We want to provide a public, open, and free API for all. And we don't want to unnecessarily burden developers (or ourselves) with cumbersome API tokens or registration processes in order to use the public REST API. For that to work, we ask that you be polite and try not to do anything that will take the public REST API down or otherwise make it unusable for others. Specifically, we encourage the following polite behaviour:
 
-- Cache data so you don't request the same data over and over again. 
+- Cache data so you don't request the same data over and over again.
 - Actively monitor API response times. If they start to go up, back-off for a while. For example, add pauses between requests and/or reduce the number of parallel requests.
 - Specify a `User-Agent` header that properly identifies your script or tool and that provides a means of contacting you vai email using "mailto:". For example:
 `GroovyBib/1.1 (https://example.org/GroovyBib/; mailto:GroovyBib@example.org) BasedOnFunkyLib/1.4`.
@@ -80,19 +78,19 @@ This way we can contact you if we see a problem.
 
 Alas, not all people are polite. And for this reason we reserve the right to impose rate limits and/or to block clients that are disrupting the public service.
 
-### Good manners = faster service.
+### Good manners = more reliable service.
 
 But we prefer carrots to sticks. As of September 18th 2017 any API queries that **use HTTPS and have appropriate contact information** will be directed to a special pool of API machines that are reserved for polite users.
 
 Why are are we doing this? Well- we don't want to force users to have to register with us. But this means that if some user of the public server writes a buggy script or ignores timeouts and errors- they can really bring the API service to its knees. What's more, it is very hard for us to identify these problem users because they tend to work off multiple parallel machines and use generic User-Agent headers. They are effectively anonymous. We're starting to have to spend a lot of time dealing with these problems and the degraded performance of the public API is affecting all the polite users as well.
 
-So... we are keeping the public service as is. It will probably continue to fluctuate widely in performance. But now, if a client connects to the API using HTTPS and provides contact information either in their User-Agent header or as a parameter on their queries, then we will send them to a separate pool of machines. We expect to be able to better control the performance of these machines because, if a script starts causing problems, we can contact the people repsonsible for the script to ask them to fix it. Or, in extremis, we can block it.
+So... we are keeping the public service as is. It will probably continue to fluctuate widely in performance. But now, if a client connects to the API using HTTPS and provides contact information either in their User-Agent header or as a parameter on their queries, then we will send them to a separate pool of machines. We expect to be able to better control the performance of these machines because, if a script starts causing problems, we can contact the people responsible for the script to ask them to fix it. Or, in extremis, we can block it.
 
 How does it work? Simple. You can do one of two things to get directed to the "polite pool":
 
 1) Include a "mailto" parameter in your query. For example:
 
-`https://api.crossref.org/works?filter=has-full-text:true&mailto=GroovyBib@example.org` 
+`https://api.crossref.org/works?filter=has-full-text:true&mailto=GroovyBib@example.org`
 
 2) Include a "mailto:" in your User-Agent header. For example:
 
@@ -100,7 +98,7 @@ How does it work? Simple. You can do one of two things to get directed to the "p
 
 Note that this only works if you query the API using HTTPS. You really should be doing that anyway (wags finger).
 
-##### Frequently anticpated questions
+##### Frequently anticipated questions
 
 **Q:** Will you spam me with marketing [bumf](https://en.oxforddictionaries.com/definition/bumf) once you have our contact info?
 
@@ -123,20 +121,19 @@ Note that this only works if you query the API using HTTPS. You really should be
 
 
 
-
 #### Rate limits
 
 From time to time Crossref needs to impose rate limits to ensure that the free API is usable by all. Any rate limits that are in effect will be advertised in the `X-Rate-Limit-Limit` and `X-Rate-Limit-Interval` HTTP headers.
 
 #### Blocking
 
-This is always our last resort, and you can generally avoid it if you include contact information in the `User-Agent` header as described above.
+This is always our last resort, and you can generally avoid it if you include contact information in the `User-Agent` header or `mailto` parameter as described above.
 
 But seriously... this is a bummer. We really want you to use the API. If you are polite about it, you shouldn't have any problems.
 
 ### Use for production services
 
-What if you want to use our API for a production service that cannot depend on the performance uncertainties of the free and open public API? What if you don't want to be affected by impolite people who do not follow the [API Etiquette](#api-etiquette) guidelines? Well, if you’re interested in using these tools or APIs for production services, we’ll soon have a service-level offering with access to all supported APIs and metadata, but with extra service and support guarantees. If you are interested in the upcoming service-based offering please contact our [outreach team](mailto://member@crossref.org). 
+What if you want to use our API for a production service that cannot depend on the performance uncertainties of the free and open public API? What if you don't want to be affected by impolite people who do not follow the [API Etiquette](#api-etiquette) guidelines? Well, if you’re interested in using these tools or APIs for production services, we’ll soon have a service-level offering with access to all supported APIs and metadata, but with extra service and support guarantees. If you are interested in the upcoming service-based offering please contact our [outreach team](mailto://member@crossref.org).
 
 ## API overview
 
@@ -146,7 +143,7 @@ The API supports HTTP and HTTPS. Examples here are provided using HTTPS.
 
 You should always url-encode DOIs and parameter values when using the API. DOIs are notorious for including characters that break URLs (e.g. semicolons, hashes, slashes, ampersands, question marks, etc.).
 
-Note that, for the sake of clarity, the examples in this document do *not* url-encode DOIs or parameter values. 
+Note that, for the sake of clarity, the examples in this document do *not* url-encode DOIs or parameter values.
 
 The API will only work for Crossref DOIs. You can test the registration agency for a DOI using the following route:
 
@@ -185,7 +182,7 @@ All results are returned in JSON. There are three general types of results:
 - Headers-only
 - Lists
 
-The mime-type for API results is `application/vnd.crossref-api-message+json` 
+The mime-type for API results is `application/vnd.crossref-api-message+json`
 
 ### Singletons
 
@@ -211,8 +208,8 @@ Lists results can contain multiple entries. Searching or filtering typically ret
     - status (e.g. "ok", error)
     - message-type (e.g. "work-list" )
     - message-version (e.g. 1.0.0 )
-    
-- Items, which will will contain the items matching the query or filter. 
+
+- Items, which will will contain the items matching the query or filter.
 
 Note that the "message-type" returned will differ from the mime-type:
 
@@ -225,7 +222,7 @@ Note that the "message-type" returned will differ from the mime-type:
 - prefix-list (list)
 - member-list (list)
 
-Normally, an API list result will return both the summary and the items. If you want to just retrieve the summary, you can do so by specifying that the number of rows returned should be zero. 
+Normally, an API list result will return both the summary and the items. If you want to just retrieve the summary, you can do so by specifying that the number of rows returned should be zero.
 
 #### Sort order
 
@@ -249,7 +246,7 @@ 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 [Funder Registry](https://github.com/Crossref/open-funder-registry)
 | `/members` | returns a list of all Crossref members (mostly publishers) |
-| `/types`      | returns a list of valid work types | 
+| `/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 |
 
@@ -287,7 +284,7 @@ Parameters can be used to query, filter and control the results returned by the
 |:-----------------------------|:----------------------------|
 | `query`                      | query terms |
 | `filter={filter_name}:{value}`| filter results by specific fields |
-| `rows={#}`                   | results per per page | 
+| `rows={#}`                   | results per per page |
 | `offset={#}` (mak 10k)               | result offset (user `cursor` for larger `/works` result sets)  |                         
 | `sample={#}` (max 100)                | return random N results |
 | `sort={#}`                   | sort results by a certain field |
@@ -308,7 +305,7 @@ Multiple filters can be specified by separating name:value pairs with a comma:
 Free form search queries can be made, for example, works that include `renear` and `ontologies`:
 
     https://api.crossref.org/works?query=renear+ontologies
-	
+
 ## Field Queries
 
 Field queries are available on the `/works` route and allow for queries that match only particular fields
@@ -316,12 +313,12 @@ of metadata. For example, this query matches records that contain the tokens `ri
 in any author field:
 
     https://api.crossref.org/works?query.author=richard+feynman
-	
+
 Field queries can be combined with the general `query` paramter and each other. Each query parameter
 is ANDed with the others:
 
     https://api.crossref.org/works?query.title=room+at+the+bottom&query.author=richard+feynman
-	
+
 ### `/works` Field Queries
 
 These field queries are available on the `/works` route:
@@ -369,14 +366,14 @@ can accept a `*` as their maximum, which indicates that all values should be ret
 Facets are specified with the `facet` parameter:
 
     https://api.crossref.org/works?rows=0&facet=type-name:*
-    
+
 | Facet name | Maximum values | Description |
 |:-----------|:---------------|-------------|
-| `affiliation` | `*` | Author affiliation | 
+| `affiliation` | `*` | Author affiliation |
 | `year` | `*` | Earliest year of publication, synonym for `published` |
 | `funder-name` | `*` | Funder literal name as deposited alongside DOIs |
 | `funder-doi` | `*` | Funder DOI |
-| `orcid` | 100 | Contributor ORCID | 
+| `orcid` | 100 | Contributor ORCID |
 | `container-title` | 100 | Work container title, such as journal title, or book title |
 | `assertion` | `*` | Custom Crossmark assertion name |
 | `archive` | `*` | Archive location |
@@ -473,24 +470,24 @@ Multiple filters can be specified in a single query. In such a case, different f
 would locate documents that are updates, were published on or after 3rd March 2014 and were funded by either the National Science Foundation (`10.13039/100000001`) or the National Heart, Lung, and Blood Institute (`10.13039/100000050`). These filters would be specified by joining each filter together with a comma:
 
     /works?filter=is-update:true,from-pub-date:2014-03-03,funder:10.13039/100000001,funder:10.13039/100000050
-    
+
 ### Dot filters
 
 A filter with a dot in its name is special. The dot signifies that the filter will be applied to some other record type that is related to primary resource record type. For example, with work queries, one can filter on works that have an award, where the same award has a particular award number and award-gving funding agency:
 
     /works?filter=award.number:CBET-0756451,award.funder:10.13039/100000001
-    
+
 Here we filter on works that have an award by the National Science Foundation that also has the award number `CBET-0756451`.
 
 ### 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.
 
 ### 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
 
@@ -506,7 +503,7 @@ You can control the delivery and selection results using the `rows`, `offset` an
 
  If you are expecting results beyond 10K, then use a `cursor` to deep page through the results. Note that not all routes support cursors.
 
-### Rows 
+### Rows
 
 Normally, results are returned 20 at a time. You can control the number of results returns by using the `rows` parameter. To limit results to 5, for example, you could do the following:
 
@@ -515,7 +512,7 @@ Normally, results are returned 20 at a time. You can control the number of resul
 If you would just like to get the `summary` of the results, you can set the rows to 0 (zero).
 
     https://api.crossref.org/works?query=allen+renear&rows=0
-    
+
 The maximum number rows you can ask for in one query is `1000`.
 
 ### Offset
@@ -535,7 +532,7 @@ Using large `offset` values can result in extremely long response times. Offsets
 A `next-cursor` field will be provided in the JSON response. To get the next page of results, pass the value of `next-cursor` as the `cursor` parameter:
 
     https://api.crossref.org/members/311/works?filter=type:journal-article&cursor=AoE/CGh0dHA6Ly9keC5kb2kub3JnLzEwLjEwMDIvdGRtX2xpY2Vuc2VfMQ==
- 
+
 Clients should check the number of returned items. If the number of returned items is fewer than the number of expected rows then the end of the result set has been reached. Using `next-cursor` beyond this point will result in responses with an empty items list.
 
 The `cursor` parameter is available on all `/works` resources.
@@ -545,7 +542,7 @@ The `cursor` parameter is available on all `/works` resources.
 Being able to select random results is useful for both testing and sampling. You can use the `sample` parameter to retrieve random results. So, for example, the following select 10 random works:
 
     https://api.crossref.org/works?sample=10
-    
+
 Note that when you use the `sample` parameter, the `rows` and `offset` parameters are ignored.
 
 
@@ -572,19 +569,19 @@ Note that the filters for license URL and maximum license embargo period (licens
 **All works where the archive partner listed = 'CLOCKSS'**
 
     https://api.crossref.org/works?filter=archive:CLOCKSS
-    
+
 **All members with `hind` in their name (e.g. Hindawi)**
 
     https://api.crossref.org/members?query=hind
-    
+
 **All licenses linked to works published by Elsevier**
 
     http://api.crossref.org/v1/works?facet=license:*&filter=member:78&rows=0
-    
+
 **All licenses applied to works published in the journal `Pathology Research International`**
 
     https://api.crossref.org/works?facet=license:*&filter=issn:2090-8091
-    
+
 **All works with an award numbered roughly `1 F31 MH11745` also awarded by funder with ID `10.13039/100000025`:
 
     https://api.crossref.org/works?filter=award.number:1F31MH11745,award.funder:10.13039/100000025
@@ -594,14 +591,14 @@ Note that the filters for license URL and maximum license embargo period (licens
 In theory, the syntax of the API can vary independently of the result representations. In practice, major version changes in either will require changes to API clients and so versioning of the API will apply to both the API syntax and the result representation.
 
 The API uses a semantic versioning scheme whereby the version number is divided into three parts delimited by periods. The first number represents the "major" release number. The second represents a "minor" release number.
-      
+
     Version 1.20
             ^  ^
             |  |
         major  |
            minor
 
- **Major** version increments 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 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 Crossref can roll out. Note that client applications should not have dependencies on minor versions, and Crossref will only maintain the latest minor version for the two most recent major versions.
 
@@ -612,14 +609,14 @@ Adding syntax options or metadata to representations will normally be backwards
 If you need to tie your implementation to a specific major version of the API, you can do so by using version-specific routes. The default route redirects to the most recent version of the API. Some older major versions may be available using a version prefix. For example, to access version `v1` of the API:
 
     https://api.crossref.orv/v1/works
-    
+
 Each major version has no backwards incompatible changes within its public interface.
 
 ## Documentation history
 
 - V1: 2013-09-08, first draft.
 - V2: 2013-09-24, reference platform deployed
-- v3: 2013-09-25, reworked filters. Added API versioning doc 
+- v3: 2013-09-25, reworked filters. Added API versioning doc
 - v4: 2013-09-25, more filter changes.
 - v5: 2013-09-27, doc mime-type and message-type relationship
 - v6: 2013-10-01, updated `sample` & added examples with filters
@@ -639,7 +636,7 @@ Each major version has no backwards incompatible changes within its public inter
 - v19: 2014-06-23, new textual filters - `container-title`, `category-name`.
 - v20: 2014-06-24, OR filter queries, `type-name` filter.
 - 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. 
+- 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.
 - v25, 2015-05-06, added link to issue tracker. Removed Warning section.

From 0114c5d32919425d42f56d9ca9d3f3df200a473d Mon Sep 17 00:00:00 2001
From: Geoffrey Bilder 
Date: Thu, 21 Sep 2017 09:47:27 +0200
Subject: [PATCH 192/219] new TOC, new filter/facet info

---
 README.md | 23 ++++++++++++++++++++++-
 1 file changed, 22 insertions(+), 1 deletion(-)

diff --git a/README.md b/README.md
index 2524366..78d8d3a 100644
--- a/README.md
+++ b/README.md
@@ -385,10 +385,14 @@ Facets are specified with the `facet` parameter:
 | `category-name` | `*` | Category name of work |
 | `relation-type` | `*` | Relation type described by work or described by another work with work as object |
 | `assertion-group` | `*` | Custom Crossmark assertion group name |
+| `publisher-name` | `*` | Publisher name of work |
 
 ## Filter names
 
-Filters allow you to narrow queries. All filter results are lists.  The following filters are supported:
+Filters allow you to narrow queries. All filter results are lists.
+
+
+The following filters are supported for the `/works` route:
 
 | filter     | possible values | description|
 |:-----------|:----------------|:-----------|
@@ -458,6 +462,22 @@ Filters allow you to narrow queries. All filter results are lists.  The followin
 | `relation.object` | | Relations where the object identifier matches the identifier provided |
 | `relation.object-type` | | One of the identifier types from the Crossref relations schema (e.g. `doi`, `issn`) |
 
+
+The following filters are supported for the `/members` route:
+
+| filter     | possible values | description|
+|:-----------|:----------------|:-----------|
+| `has-public-references` | | Member has made their references public for one or more of their prefixes |
+| `backfile-doi-count` | {integer} | count of DOIs for material published more than two years ago |
+| `current-doi-count` | {integer} | count of DOIs for material published within last two years |
+
+The following filters are supported for the `/funders` route:
+
+| filter     | possible values | description|
+|:-----------|:----------------|:-----------|
+| `location` | | funders located in specified country |
+
+
 ### Multiple filters
 
 Multiple filters can be specified in a single query. In such a case, different filters will be applied with AND semantics, while specifying the same filter multiple times will result in OR semantics - that is, specifying the filters:
@@ -669,3 +689,4 @@ Each major version has no backwards incompatible changes within its public inter
 - v52, 2017-07-27, removed service notice and what's new section.
 - v53, 2017-08-11, mention `full-text.application` filter
 - v54, 2017-09-18, add info about new "polite pool"
+- v55, 2017-09-21, add info about `/member` and `/funder` filters. add info about `publisher-name` facet.

From 71970b1ed4340c2556ac96b0dbc6b4f6ed71998b Mon Sep 17 00:00:00 2001
From: Geoffrey Bilder 
Date: Thu, 21 Sep 2017 10:33:30 +0200
Subject: [PATCH 193/219] select parameter

---
 README.md | 8 +++++++-
 1 file changed, 7 insertions(+), 1 deletion(-)

diff --git a/README.md b/README.md
index 78d8d3a..f3f0827 100644
--- a/README.md
+++ b/README.md
@@ -228,6 +228,12 @@ Normally, an API list result will return both the summary and the items. If you
 
 If the API call includes a query, then the sort order will be by the relevance score. If no query is included, then the sort order will be by DOI update date.
 
+### Selecting which elements to return
+
+Crossref metadata records can be quite large. Sometimes you just want a few elements from the schema. You can "select" a subset of elements to return using the `select` parameter. This can make your API calls much more efficient. For example:
+
+`http://api.crossref.org/works?sample=10&select=DOI,title`
+
 
 ## Resource components
 Major resource components supported by the Crossref API are:
@@ -689,4 +695,4 @@ Each major version has no backwards incompatible changes within its public inter
 - v52, 2017-07-27, removed service notice and what's new section.
 - v53, 2017-08-11, mention `full-text.application` filter
 - v54, 2017-09-18, add info about new "polite pool"
-- v55, 2017-09-21, add info about `/member` and `/funder` filters. add info about `publisher-name` facet.
+- v55, 2017-09-21, document `/member` and `/funder` filters. document `publisher-name` facet. document `select` parameter.

From 3c2ffd03d63bda17a17da48ffdcb7c3abe9fa989 Mon Sep 17 00:00:00 2001
From: Geoffrey Bilder 
Date: Fri, 22 Sep 2017 15:33:13 +0200
Subject: [PATCH 194/219] update some demos

---
 demos/api-demo.postman_collection.json     | 612 +++++++++++++++++++++
 {jupyter => demos}/crossref-api-demo.ipynb |  24 +-
 2 files changed, 618 insertions(+), 18 deletions(-)
 create mode 100644 demos/api-demo.postman_collection.json
 rename {jupyter => demos}/crossref-api-demo.ipynb (98%)

diff --git a/demos/api-demo.postman_collection.json b/demos/api-demo.postman_collection.json
new file mode 100644
index 0000000..be5049c
--- /dev/null
+++ b/demos/api-demo.postman_collection.json
@@ -0,0 +1,612 @@
+{
+	"variables": [],
+	"info": {
+		"name": "api-demo",
+		"_postman_id": "34579ef5-e86d-c116-c607-eeae07a1dae5",
+		"description": "Crossref REST API demo",
+		"schema": "https://schema.getpostman.com/json/collection/v2.0.0/collection.json"
+	},
+	"item": [
+		{
+			"name": "members",
+			"request": {
+				"url": "https://api.crossref.org/members",
+				"method": "GET",
+				"header": [],
+				"body": {},
+				"description": ""
+			},
+			"response": []
+		},
+		{
+			"name": "find a member",
+			"request": {
+				"url": {
+					"raw": "https://api.crossref.org/members?query=\"Hindawi\"",
+					"protocol": "https",
+					"host": [
+						"api",
+						"crossref",
+						"org"
+					],
+					"path": [
+						"members"
+					],
+					"query": [
+						{
+							"key": "query",
+							"value": "\"Hindawi\"",
+							"equals": true,
+							"description": ""
+						}
+					],
+					"variable": []
+				},
+				"method": "GET",
+				"header": [],
+				"body": {},
+				"description": ""
+			},
+			"response": []
+		},
+		{
+			"name": "a specific member",
+			"request": {
+				"url": "https://api.crossref.org/members/78",
+				"method": "GET",
+				"header": [],
+				"body": {},
+				"description": ""
+			},
+			"response": []
+		},
+		{
+			"name": "members with open references",
+			"request": {
+				"url": {
+					"raw": "https://api.crossref.org/members?filter=has-public-references:true",
+					"protocol": "https",
+					"host": [
+						"api",
+						"crossref",
+						"org"
+					],
+					"path": [
+						"members"
+					],
+					"query": [
+						{
+							"key": "filter",
+							"value": "has-public-references:true",
+							"equals": true,
+							"description": ""
+						}
+					],
+					"variable": []
+				},
+				"method": "GET",
+				"header": [],
+				"body": {},
+				"description": ""
+			},
+			"response": []
+		},
+		{
+			"name": "journals",
+			"request": {
+				"url": "https://api.crossref.org/journals",
+				"method": "GET",
+				"header": [],
+				"body": {},
+				"description": ""
+			},
+			"response": []
+		},
+		{
+			"name": "specific journal",
+			"request": {
+				"url": "https://api.crossref.org/journals/1476-4687",
+				"method": "GET",
+				"header": [],
+				"body": {},
+				"description": ""
+			},
+			"response": []
+		},
+		{
+			"name": "types",
+			"request": {
+				"url": "https://api.crossref.org/types",
+				"method": "GET",
+				"header": [],
+				"body": {},
+				"description": ""
+			},
+			"response": []
+		},
+		{
+			"name": "works",
+			"request": {
+				"url": "https://api.crossref.org/works",
+				"method": "GET",
+				"header": [],
+				"body": {},
+				"description": ""
+			},
+			"response": []
+		},
+		{
+			"name": "a specific work",
+			"request": {
+				"url": "https://api.crossref.org/works/10.1371/journal.pbio.2001655",
+				"method": "GET",
+				"header": [],
+				"body": {},
+				"description": ""
+			},
+			"response": []
+		},
+		{
+			"name": "another specific work",
+			"request": {
+				"url": "https://api.crossref.org/works/10.6084/m9.figshare.1314859.v1",
+				"method": "GET",
+				"header": [],
+				"body": {},
+				"description": ""
+			},
+			"response": []
+		},
+		{
+			"name": "what the hell?",
+			"request": {
+				"url": "https://api.crossref.org/works/10.6084/m9.figshare.1314859.v1/agency",
+				"method": "GET",
+				"header": [],
+				"body": {},
+				"description": ""
+			},
+			"response": []
+		},
+		{
+			"name": "a Crossref DOI",
+			"request": {
+				"url": "https://api.crossref.org/works/10.1371/journal.pbio.2001655/agency",
+				"method": "GET",
+				"header": [],
+				"body": {},
+				"description": ""
+			},
+			"response": []
+		},
+		{
+			"name": "10 random works",
+			"request": {
+				"url": {
+					"raw": "https://api.crossref.org/works?sample=10",
+					"protocol": "https",
+					"host": [
+						"api",
+						"crossref",
+						"org"
+					],
+					"path": [
+						"works"
+					],
+					"query": [
+						{
+							"key": "sample",
+							"value": "10",
+							"equals": true,
+							"description": ""
+						}
+					],
+					"variable": []
+				},
+				"method": "GET",
+				"header": [],
+				"body": {},
+				"description": ""
+			},
+			"response": []
+		},
+		{
+			"name": "works that are monographs",
+			"request": {
+				"url": {
+					"raw": "https://api.crossref.org/works?filter=type:monograph",
+					"protocol": "https",
+					"host": [
+						"api",
+						"crossref",
+						"org"
+					],
+					"path": [
+						"works"
+					],
+					"query": [
+						{
+							"key": "filter",
+							"value": "type:monograph",
+							"equals": true,
+							"description": ""
+						}
+					],
+					"variable": []
+				},
+				"method": "GET",
+				"header": [],
+				"body": {},
+				"description": ""
+			},
+			"response": []
+		},
+		{
+			"name": "works containing \"zika\"",
+			"request": {
+				"url": {
+					"raw": "https://api.crossref.org/works?query=\"zika\"",
+					"protocol": "https",
+					"host": [
+						"api",
+						"crossref",
+						"org"
+					],
+					"path": [
+						"works"
+					],
+					"query": [
+						{
+							"key": "query",
+							"value": "\"zika\"",
+							"equals": true,
+							"description": ""
+						}
+					],
+					"variable": []
+				},
+				"method": "GET",
+				"header": [],
+				"body": {},
+				"description": ""
+			},
+			"response": []
+		},
+		{
+			"name": "works containing \"zika\" in title",
+			"request": {
+				"url": {
+					"raw": "https://api.crossref.org/works?query.title=\"zika\"",
+					"protocol": "https",
+					"host": [
+						"api",
+						"crossref",
+						"org"
+					],
+					"path": [
+						"works"
+					],
+					"query": [
+						{
+							"key": "query.title",
+							"value": "\"zika\"",
+							"equals": true,
+							"description": ""
+						}
+					],
+					"variable": []
+				},
+				"method": "GET",
+				"header": [],
+				"body": {},
+				"description": ""
+			},
+			"response": []
+		},
+		{
+			"name": "works containing \"zika\" faceted by top ten funders",
+			"request": {
+				"url": {
+					"raw": "https://api.crossref.org/works?query.title=\"zika\"&facet=funder-name:10",
+					"protocol": "https",
+					"host": [
+						"api",
+						"crossref",
+						"org"
+					],
+					"path": [
+						"works"
+					],
+					"query": [
+						{
+							"key": "query.title",
+							"value": "\"zika\"",
+							"equals": true,
+							"description": ""
+						},
+						{
+							"key": "facet",
+							"value": "funder-name:10",
+							"equals": true,
+							"description": ""
+						}
+					],
+					"variable": []
+				},
+				"method": "GET",
+				"header": [],
+				"body": {},
+				"description": ""
+			},
+			"response": []
+		},
+		{
+			"name": "works containing \"zika\" faceted by top ten publishers",
+			"request": {
+				"url": {
+					"raw": "https://api.crossref.org/works?query.title=\"zika\"&facet=publisher-name:10",
+					"protocol": "https",
+					"host": [
+						"api",
+						"crossref",
+						"org"
+					],
+					"path": [
+						"works"
+					],
+					"query": [
+						{
+							"key": "query.title",
+							"value": "\"zika\"",
+							"equals": true,
+							"description": ""
+						},
+						{
+							"key": "facet",
+							"value": "publisher-name:10",
+							"equals": true,
+							"description": ""
+						}
+					],
+					"variable": []
+				},
+				"method": "GET",
+				"header": [],
+				"body": {},
+				"description": ""
+			},
+			"response": []
+		},
+		{
+			"name": "works- matching a reference",
+			"request": {
+				"url": {
+					"raw": "https://api.crossref.org/works?query.bibliographic=Neylon, C., Pattinson, D., Bilder, G.,  Lin, J. (2017). On the origin of nonequivalent states: How we can talk about preprints. F1000Research, 6, 608.",
+					"protocol": "https",
+					"host": [
+						"api",
+						"crossref",
+						"org"
+					],
+					"path": [
+						"works"
+					],
+					"query": [
+						{
+							"key": "query.bibliographic",
+							"value": "Neylon, C., Pattinson, D., Bilder, G.,  Lin, J. (2017). On the origin of nonequivalent states: How we can talk about preprints. F1000Research, 6, 608.",
+							"equals": true,
+							"description": ""
+						}
+					],
+					"variable": []
+				},
+				"method": "GET",
+				"header": [],
+				"body": {},
+				"description": ""
+			},
+			"response": []
+		},
+		{
+			"name": "works that have a full text link + a license",
+			"request": {
+				"url": {
+					"raw": "https://api.crossref.org/works?filter=has-full-text:true,has-license:true",
+					"protocol": "https",
+					"host": [
+						"api",
+						"crossref",
+						"org"
+					],
+					"path": [
+						"works"
+					],
+					"query": [
+						{
+							"key": "filter",
+							"value": "has-full-text:true,has-license:true",
+							"equals": true,
+							"description": ""
+						}
+					],
+					"variable": []
+				},
+				"method": "GET",
+				"header": [],
+				"body": {},
+				"description": ""
+			},
+			"response": []
+		},
+		{
+			"name": "a work's updates",
+			"request": {
+				"url": {
+					"raw": "https://api.crossref.org/works?filter=updates:10.1007/s00540-006-0468-8",
+					"protocol": "https",
+					"host": [
+						"api",
+						"crossref",
+						"org"
+					],
+					"path": [
+						"works"
+					],
+					"query": [
+						{
+							"key": "filter",
+							"value": "updates:10.1007/s00540-006-0468-8",
+							"equals": true,
+							"description": ""
+						}
+					],
+					"variable": []
+				},
+				"method": "GET",
+				"header": [],
+				"body": {},
+				"description": ""
+			},
+			"response": []
+		},
+		{
+			"name": "works with orcid faceted by top 10 publishers",
+			"request": {
+				"url": {
+					"raw": "http://api.crossref.org/works?filter=has-orcid:true&facet=publisher-name:10&rows=0",
+					"protocol": "http",
+					"host": [
+						"api",
+						"crossref",
+						"org"
+					],
+					"path": [
+						"works"
+					],
+					"query": [
+						{
+							"key": "filter",
+							"value": "has-orcid:true",
+							"equals": true,
+							"description": ""
+						},
+						{
+							"key": "facet",
+							"value": "publisher-name:10",
+							"equals": true,
+							"description": ""
+						},
+						{
+							"key": "rows",
+							"value": "0",
+							"equals": true,
+							"description": ""
+						}
+					],
+					"variable": []
+				},
+				"method": "GET",
+				"header": [],
+				"body": {},
+				"description": ""
+			},
+			"response": []
+		},
+		{
+			"name": "funders",
+			"request": {
+				"url": "https://api.crossref.org/funders",
+				"method": "GET",
+				"header": [],
+				"body": {},
+				"description": ""
+			},
+			"response": []
+		},
+		{
+			"name": "funders in United Kingdom",
+			"request": {
+				"url": {
+					"raw": "https://api.crossref.org/funders?filter=location:United Kingdom",
+					"protocol": "https",
+					"host": [
+						"api",
+						"crossref",
+						"org"
+					],
+					"path": [
+						"funders"
+					],
+					"query": [
+						{
+							"key": "filter",
+							"value": "location:United Kingdom",
+							"equals": true,
+							"description": ""
+						}
+					],
+					"variable": []
+				},
+				"method": "GET",
+				"header": [],
+				"body": {},
+				"description": ""
+			},
+			"response": []
+		},
+		{
+			"name": "find a funder",
+			"request": {
+				"url": {
+					"raw": "https://api.crossref.org/funders?query=\"Wellcome\"",
+					"protocol": "https",
+					"host": [
+						"api",
+						"crossref",
+						"org"
+					],
+					"path": [
+						"funders"
+					],
+					"query": [
+						{
+							"key": "query",
+							"value": "\"Wellcome\"",
+							"equals": true,
+							"description": ""
+						}
+					],
+					"variable": []
+				},
+				"method": "GET",
+				"header": [],
+				"body": {},
+				"description": ""
+			},
+			"response": []
+		},
+		{
+			"name": "a specific funder",
+			"request": {
+				"url": "https://api.crossref.org/funders/100000936",
+				"method": "GET",
+				"header": [],
+				"body": {},
+				"description": ""
+			},
+			"response": []
+		},
+		{
+			"name": "a funder sub-organisation",
+			"request": {
+				"url": "https://api.crossref.org/funders/100008902",
+				"method": "GET",
+				"header": [],
+				"body": {},
+				"description": ""
+			},
+			"response": []
+		}
+	]
+}
\ No newline at end of file
diff --git a/jupyter/crossref-api-demo.ipynb b/demos/crossref-api-demo.ipynb
similarity index 98%
rename from jupyter/crossref-api-demo.ipynb
rename to demos/crossref-api-demo.ipynb
index 08eb75f..c77c8dc 100644
--- a/jupyter/crossref-api-demo.ipynb
+++ b/demos/crossref-api-demo.ipynb
@@ -100,7 +100,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 3,
+   "execution_count": null,
    "metadata": {
     "button": false,
     "collapsed": true,
@@ -130,7 +130,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 4,
+   "execution_count": null,
    "metadata": {
     "button": false,
     "new_sheet": false,
@@ -138,18 +138,7 @@
      "read_only": false
     }
    },
-   "outputs": [
-    {
-     "data": {
-      "text/plain": [
-       "90760017"
-      ]
-     },
-     "execution_count": 4,
-     "metadata": {},
-     "output_type": "execute_result"
-    }
-   ],
+   "outputs": [],
    "source": [
     "works.count()"
    ]
@@ -765,7 +754,7 @@
    "source": [
     "## Fun with facets\n",
     "\n",
-    "### Orchid support"
+    "### ORCID support"
    ]
   },
   {
@@ -892,9 +881,7 @@
   {
    "cell_type": "code",
    "execution_count": null,
-   "metadata": {
-    "collapsed": true
-   },
+   "metadata": {},
    "outputs": [],
    "source": [
     "from crossref.restful import Works\n",
@@ -988,6 +975,7 @@
    "execution_count": null,
    "metadata": {
     "button": false,
+    "collapsed": true,
     "new_sheet": false,
     "run_control": {
      "read_only": false

From cc13e92a3a3c68252adfac360624cf09b8479d2e Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Ivan=20Mas=C3=A1r?= 
Date: Fri, 29 Sep 2017 13:53:26 +0200
Subject: [PATCH 195/219] fix typos in Jupyter notebook

---
 demos/crossref-api-demo.ipynb | 32 ++++++++++++++++----------------
 1 file changed, 16 insertions(+), 16 deletions(-)

diff --git a/demos/crossref-api-demo.ipynb b/demos/crossref-api-demo.ipynb
index c77c8dc..971a21d 100644
--- a/demos/crossref-api-demo.ipynb
+++ b/demos/crossref-api-demo.ipynb
@@ -21,7 +21,7 @@
     "\n",
     "The examples here are in Python 3. Sorry- but you're going to have to make the move sometime ;)\n",
     "\n",
-    "To use this librarary you can:\n",
+    "To use this libra ry you can:\n",
     "\n",
     "`pip install crossrefapi`\n",
     "\n",
@@ -91,9 +91,9 @@
    "source": [
     "## Working with \"works\"\n",
     "\n",
-    "Let's start by looking breifly looking at\"works\". The route refers to items identified by a DOI in the index. These can be articles, books, components, etc.\n",
+    "Let's start by looking briefly looking at\"works\". The route refers to items identified by a DOI in the index. These can be articles, books, components, etc.\n",
     "\n",
-    "**TIP:** Crossref does not use \"works\" in the [FRBR](https://en.wikipedia.org/wiki/Functional_Requirements_for_Bibliographic_Records) sense of the word. In Crossref parlance, a \"work\" is just a thing identifed by a DOI. In practice, Crossref DOIs are used as citaton identifiers. So, in FRBR terms, this means, that a Crossref DOI tends to refer to one _expression_ which might include multiple _manifestations_. So, for example, the ePub, HTML and PDF version of an article will share a Crossref DOI because the differences between them should not effect the interpretation or crediting of the content. In short, they can be cited interchangeabley. The same is true of the \"accepted manuscript\" and the \"version-of-record\" of that accepted manuscript.\n",
+    "**TIP:** Crossref does not use \"works\" in the [FRBR](https://en.wikipedia.org/wiki/Functional_Requirements_for_Bibliographic_Records) sense of the word. In Crossref parlance, a \"work\" is just a thing identified by a DOI. In practice, Crossref DOIs are used as citation identifiers. So, in FRBR terms, this means, that a Crossref DOI tends to refer to one _expression_ which might include multiple _manifestations_. So, for example, the ePub, HTML and PDF version of an article will share a Crossref DOI because the differences between them should not effect the interpretation or crediting of the content. In short, they can be cited interchangeably. The same is true of the \"accepted manuscript\" and the \"version-of-record\" of that accepted manuscript.\n",
     "\n",
     "In order to start querying information about works, we need to import the library and make things convenient."
    ]
@@ -153,7 +153,7 @@
     }
    },
    "source": [
-    "Note that above I said \"How many Crossref DOIs\". There are several other [DOI registration agencies](https://www.doi.org/registration_agencies.html). Crossref is by far he largest DOI RA, and the other RAs tend to specialize in orthoganal areas (e.g. Music & Video, Local language translations of publications, etc.) but it is important to not that this API will not work with non-Crossref DOIs (though [DataCite](www.datacite.org], another RA, provides a very similar API).\n",
+    "Note that above I said \"How many Crossref DOIs\". There are several other [DOI registration agencies](https://www.doi.org/registration_agencies.html). Crossref is by far the largest DOI RA, and the other RAs tend to specialize in orthogonal areas (e.g. Music & Video, Local language translations of publications, etc.) but it is important to note that this API will not work with non-Crossref DOIs (though [DataCite](www.datacite.org]), another RA, provides a very similar API).\n",
     "\n",
     "**TIP:** Not all DOIs are Crossref DOIs. If you are having trouble using a DOI with Crossref's API, check to see if it is a Crossref DOI.\n",
     "\n",
@@ -244,7 +244,7 @@
     }
    },
    "source": [
-    "This is bascially a huge JSON object, so you can retreive individual elements from it. Here is the publisher:"
+    "This is basically a huge JSON object, so you can retrieve individual elements from it. Here is the publisher:"
    ]
   },
   {
@@ -272,7 +272,7 @@
     }
    },
    "source": [
-    "And here is the license for the \"verson of record\":"
+    "And here is the license for the \"version of record\":"
    ]
   },
   {
@@ -303,7 +303,7 @@
    "source": [
     "Um... That was complicated. What does 'vor' mean?\n",
     "\n",
-    "**TIP:** Publishers sometimes record information for multiple versions of the content identified by a DOI. These versions should be interchaneable from the point of view of citation, but sometimes one version has more \"features\" than another. For example, it might be typset or have references linked, etc. The two versions might also have different licenses and different URLs. The terminology publishers use for identifying versions comes from the [NISO standard call JAV (Journal Artcle Version)](http://www.niso.org/publications/rp/RP-8-2008.pdf) and, although this terminology is [sometimes problematic](https://f1000research.com/articles/6-608/v1), you should be aware of it. In particualr, you will see two terms used  in Crossref metadata:\n",
+    "**TIP:** Publishers sometimes record information for multiple versions of the content identified by a DOI. These versions should be interchangeable from the point of view of citation, but sometimes one version has more \"features\" than another. For example, it might be typset or have references linked, etc. The two versions might also have different licenses and different URLs. The terminology publishers use for identifying versions comes from the [NISO standard called JAV (Journal Artcle Version)](http://www.niso.org/publications/rp/RP-8-2008.pdf) and, although this terminology is [sometimes problematic](https://f1000research.com/articles/6-608/v1), you should be aware of it. In particular, you will see two terms used  in Crossref metadata:\n",
     "\n",
     "- `VOR` = Version of Record\n",
     "- `AM` = Accepted Manuscript\n",
@@ -332,7 +332,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "The above has given us a brief overview of how to get a record and elements of a record identified with a Crossref DOI. Obviously, the goald is to do this in bulk. That is, to select and process records for multiple Crossref DOIs. Before we do that, it is helpful to familiarise yourself with some of the other \"routes\" supported by the REST API. This is because more advanced usage of the API typically involveds combining information from several routes. "
+    "The above has given us a brief overview of how to get a record and elements of a record identified with a Crossref DOI. Obviously, the goald is to do this in bulk. That is, to select and process records for multiple Crossref DOIs. Before we do that, it is helpful to familiarise yourself with some of the other \"routes\" supported by the REST API. This is because more advanced usage of the API typically involves combining information from several routes. "
    ]
   },
   {
@@ -402,7 +402,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "Let's look at a partciularmember, Hindawi:"
+    "Let's look at a partciular member, Hindawi:"
    ]
   },
   {
@@ -425,7 +425,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "**TIP:** Many people make the mistake of thinking that a \"DOI prefix\" can be used to identify the member responsible for a Crossref DOI. This is not true. DOI prefixes merely serve as a namspace form which a member can create new DOIs without worrying about collisions. But, once created, Crossref DOIs are often transfered between publishers and so a Crossref member will often be responsible for DOIs with a variety of prefixes. So, for example, above, Hindawi is responsible for several prefixes:"
+    "**TIP:** Many people make the mistake of thinking that a \"DOI prefix\" can be used to identify the member responsible for a Crossref DOI. This is not true. DOI prefixes merely serve as a namespace form which a member can create new DOIs without worrying about collisions. But, once created, Crossref DOIs are often transfered between publishers and so a Crossref member will often be responsible for DOIs with a variety of prefixes. So, for example, above, Hindawi is responsible for several prefixes:"
    ]
   },
   {
@@ -679,7 +679,7 @@
     }
    },
    "source": [
-    "A publisher record also contains a useful summary of the member's metadata and the Crossref services that they particpate in.\n",
+    "A publisher record also contains a useful summary of the member's metadata and the Crossref services that they participate in.\n",
     "\n",
     "Let's look at what percentage of their metadata includes certain information:"
    ]
@@ -727,7 +727,7 @@
     }
    },
    "source": [
-    "Now let's see what Crossref services they particpate in:"
+    "Now let's see what Crossref services they participate in:"
    ]
   },
   {
@@ -742,8 +742,8 @@
    },
    "outputs": [],
    "source": [
-    "particpation = [[key,pub['flags'][key]] for key in pub['flags'].keys()]\n",
-    "f = pd.DataFrame(particpation)\n",
+    "participation = [[key,pub['flags'][key]] for key in pub['flags'].keys()]\n",
+    "f = pd.DataFrame(participation)\n",
     "f.columns = ['service','paticipation']\n",
     "f"
    ]
@@ -796,7 +796,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "## Some outher resources\n",
+    "## Some other resources\n",
     "\n",
     "### Types"
    ]
@@ -915,7 +915,7 @@
     }
    },
    "source": [
-    "Works records indexed _today_ that have affiliatioon data"
+    "Works records indexed _today_ that have affiliation data"
    ]
   },
   {

From c1231fb49c26d4a0fb897f4725b476411fbda819 Mon Sep 17 00:00:00 2001
From: Geoffrey Bilder 
Date: Tue, 10 Oct 2017 12:56:55 +0200
Subject: [PATCH 196/219] update example email addresses in sample deposit
 files.

---
 examples/full-crossmark.xml    | 6 +++---
 examples/partial-crossmark.xml | 6 +++---
 examples/partial-funders.xml   | 6 +++---
 examples/partial-licenses.xml  | 6 +++---
 examples/partial-resources.xml | 6 +++---
 5 files changed, 15 insertions(+), 15 deletions(-)

diff --git a/examples/full-crossmark.xml b/examples/full-crossmark.xml
index e8c953e..f2ea129 100644
--- a/examples/full-crossmark.xml
+++ b/examples/full-crossmark.xml
@@ -4,14 +4,14 @@
 	   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
 	   xmlns:ai="http://www.crossref.org/AccessIndicators.xsd"
 	   xmlns:fr="http://www.crossref.org/fundref.xsd"
-	   xsi:schemaLocation="http://www.crossref.org/schema/4.3.4 
+	   xsi:schemaLocation="http://www.crossref.org/schema/4.3.4
 			       http://www.crossref.org/schema/deposit/crossref4.3.4.xsd">
   
     123456
     1385985547
     
-      Karl Ward
-      kward@crossref.org
+      Jane Bloggs
+      jbloggs@example.com
     
     creftest
   
diff --git a/examples/partial-crossmark.xml b/examples/partial-crossmark.xml
index 90163ec..6f609d4 100644
--- a/examples/partial-crossmark.xml
+++ b/examples/partial-crossmark.xml
@@ -4,13 +4,13 @@
 	   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
 	   xmlns:ai="http://www.crossref.org/AccessIndicators.xsd"
 	   xmlns:fr="http://www.crossref.org/fundref.xsd"
-	   xsi:schemaLocation="http://www.crossref.org/doi_resources_schema/4.3.2 
+	   xsi:schemaLocation="http://www.crossref.org/doi_resources_schema/4.3.2
 			       http://www.crossref.org/schema/deposit/doi_resources4.3.2.xsd">
   
     123456
     
-      Karl Ward
-      kward@crossref.org
+      Jane Bloggs
+      jbloggs@example.com
     
   
   
diff --git a/examples/partial-funders.xml b/examples/partial-funders.xml
index f334f3f..b168c95 100644
--- a/examples/partial-funders.xml
+++ b/examples/partial-funders.xml
@@ -3,13 +3,13 @@
 	   xmlns="http://www.crossref.org/doi_resources_schema/4.3.2"
 	   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
 	   xmlns:fr="http://www.crossref.org/fundref.xsd"
-	   xsi:schemaLocation="http://www.crossref.org/doi_resources_schema/4.3.2 
+	   xsi:schemaLocation="http://www.crossref.org/doi_resources_schema/4.3.2
 			       http://www.crossref.org/schema/deposit/doi_resources4.3.2.xsd">
   
     123456
     
-      Karl Ward
-      kward@crossref.org
+      Jane Bloggs
+      jbloggs@example.com
     
   
   
diff --git a/examples/partial-licenses.xml b/examples/partial-licenses.xml
index b7fd749..9676f8f 100644
--- a/examples/partial-licenses.xml
+++ b/examples/partial-licenses.xml
@@ -3,13 +3,13 @@
 	   xmlns="http://www.crossref.org/doi_resources_schema/4.3.2"
 	   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
 	   xmlns:ai="http://www.crossref.org/AccessIndicators.xsd"
-	   xsi:schemaLocation="http://www.crossref.org/doi_resources_schema/4.3.2 
+	   xsi:schemaLocation="http://www.crossref.org/doi_resources_schema/4.3.2
 			       http://www.crossref.org/schema/deposit/doi_resources4.3.2.xsd">
   
     123456
     
-      Karl Ward
-      kward@crossref.org
+      Jane Bloggs
+      jbloggs@example.com
     
   
   
diff --git a/examples/partial-resources.xml b/examples/partial-resources.xml
index b439e8e..7a74c1a 100644
--- a/examples/partial-resources.xml
+++ b/examples/partial-resources.xml
@@ -2,13 +2,13 @@
 
   
     123456
     
-      Karl Ward
-      kward@crossref.org
+      Jane Bloggs
+      jbloggs@example.com
     
   
   

From 3f459553894a0ff20b4d3565706d095a365af988 Mon Sep 17 00:00:00 2001
From: Geoffrey Bilder 
Date: Wed, 22 Nov 2017 11:28:18 +0100
Subject: [PATCH 197/219] clarify descriptions in sorting section

---
 README.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/README.md b/README.md
index f3f0827..d8ae47a 100644
--- a/README.md
+++ b/README.md
@@ -357,8 +357,8 @@ sorted. Possible values are:
 | `published-print` | Sort by print publication date |
 | `published-online` | Sort by online publication date |
 | `issued` | Sort by issued date (earliest known publication date) |
-| `is-referenced-by-count` | Sort by number of references to documents |
-| `references-count` | Sort by number of references made by documents |
+| `is-referenced-by-count` | Sort by number of times this DOI is referenced by other Crossref DOIs |
+| `references-count` | Sort by number of references included in the references section of the document identified by this DOI |
 
 An example that sorts results in order of publication, beginning with the least recent:
 

From f848c2ff6178b28e4f1e42ae217e927a8f15a771 Mon Sep 17 00:00:00 2001
From: MikeYalter 
Date: Wed, 10 Jan 2018 12:01:11 -0500
Subject: [PATCH 198/219] fixed typo

---
 README.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/README.md b/README.md
index d8ae47a..55ff0d8 100644
--- a/README.md
+++ b/README.md
@@ -338,7 +338,7 @@ These field queries are available on the `/works` route:
 | `query.chair` | Query chair given and family names |
 | `query.translator` | Query translator given and family names |
 | `query.contributor` | Query author, editor, chair and translator given and family names |
-| `query.bibliographic` | Query bibliographic infomration, useful for citation look up. Includes titles, authors, ISSNs and publication years |
+| `query.bibliographic` | Query bibliographic information, useful for citation look up. Includes titles, authors, ISSNs and publication years |
 | `query.affiliation` | Query contributor affiliations |
 
 ## Sorting

From c7c9e17123194b072b92c382826932d4035577cf Mon Sep 17 00:00:00 2001
From: Philipp Zumstein 
Date: Fri, 12 Jan 2018 11:20:10 +0100
Subject: [PATCH 199/219] [IPython notebook] Fix typos, urls, swaped code

---
 demos/crossref-api-demo.ipynb | 22 +++++++++++-----------
 1 file changed, 11 insertions(+), 11 deletions(-)

diff --git a/demos/crossref-api-demo.ipynb b/demos/crossref-api-demo.ipynb
index c77c8dc..01ae9c4 100644
--- a/demos/crossref-api-demo.ipynb
+++ b/demos/crossref-api-demo.ipynb
@@ -17,7 +17,7 @@
     "[`https://www.crossref.org/works`](https://api.crossref.org/works)\n",
     "\n",
     "\n",
-    "This means the REST API is pretty easy to use with basic low level HTTP libraries(e.g. Python's `requests`), but for this tutorial we are going to use a [higher level python library](https://github.com/fabiobatalha/crossrefapi) developed by Fabio Batalha C. Santos at [Scielo](www.scielo.org).\n",
+    "This means the REST API is pretty easy to use with basic low level HTTP libraries(e.g. Python's `requests`), but for this tutorial we are going to use a [higher level python library](https://github.com/fabiobatalha/crossrefapi) developed by Fabio Batalha C. Santos at [SciELO](http://www.scielo.org).\n",
     "\n",
     "The examples here are in Python 3. Sorry- but you're going to have to make the move sometime ;)\n",
     "\n",
@@ -91,7 +91,7 @@
    "source": [
     "## Working with \"works\"\n",
     "\n",
-    "Let's start by looking breifly looking at\"works\". The route refers to items identified by a DOI in the index. These can be articles, books, components, etc.\n",
+    "Let's start by looking briefly at\"works\". The route refers to items identified by a DOI in the index. These can be articles, books, components, etc.\n",
     "\n",
     "**TIP:** Crossref does not use \"works\" in the [FRBR](https://en.wikipedia.org/wiki/Functional_Requirements_for_Bibliographic_Records) sense of the word. In Crossref parlance, a \"work\" is just a thing identifed by a DOI. In practice, Crossref DOIs are used as citaton identifiers. So, in FRBR terms, this means, that a Crossref DOI tends to refer to one _expression_ which might include multiple _manifestations_. So, for example, the ePub, HTML and PDF version of an article will share a Crossref DOI because the differences between them should not effect the interpretation or crediting of the content. In short, they can be cited interchangeabley. The same is true of the \"accepted manuscript\" and the \"version-of-record\" of that accepted manuscript.\n",
     "\n",
@@ -153,7 +153,7 @@
     }
    },
    "source": [
-    "Note that above I said \"How many Crossref DOIs\". There are several other [DOI registration agencies](https://www.doi.org/registration_agencies.html). Crossref is by far he largest DOI RA, and the other RAs tend to specialize in orthoganal areas (e.g. Music & Video, Local language translations of publications, etc.) but it is important to not that this API will not work with non-Crossref DOIs (though [DataCite](www.datacite.org], another RA, provides a very similar API).\n",
+    "Note that above I said \"How many Crossref DOIs\". There are several other [DOI registration agencies](https://www.doi.org/registration_agencies.html). Crossref is by far he largest DOI RA, and the other RAs tend to specialize in orthoganal areas (e.g. Music & Video, Local language translations of publications, etc.) but it is important to not that this API will not work with non-Crossref DOIs (though [DataCite](https://www.datacite.org/), another RA, provides a very similar API).\n",
     "\n",
     "**TIP:** Not all DOIs are Crossref DOIs. If you are having trouble using a DOI with Crossref's API, check to see if it is a Crossref DOI.\n",
     "\n",
@@ -272,7 +272,7 @@
     }
    },
    "source": [
-    "And here is the license for the \"verson of record\":"
+    "And here is the license for the \"version of record\":"
    ]
   },
   {
@@ -303,7 +303,7 @@
    "source": [
     "Um... That was complicated. What does 'vor' mean?\n",
     "\n",
-    "**TIP:** Publishers sometimes record information for multiple versions of the content identified by a DOI. These versions should be interchaneable from the point of view of citation, but sometimes one version has more \"features\" than another. For example, it might be typset or have references linked, etc. The two versions might also have different licenses and different URLs. The terminology publishers use for identifying versions comes from the [NISO standard call JAV (Journal Artcle Version)](http://www.niso.org/publications/rp/RP-8-2008.pdf) and, although this terminology is [sometimes problematic](https://f1000research.com/articles/6-608/v1), you should be aware of it. In particualr, you will see two terms used  in Crossref metadata:\n",
+    "**TIP:** Publishers sometimes record information for multiple versions of the content identified by a DOI. These versions should be interchaneable from the point of view of citation, but sometimes one version has more \"features\" than another. For example, it might be typset or have references linked, etc. The two versions might also have different licenses and different URLs. The terminology publishers use for identifying versions comes from the [NISO standard call JAV (Journal Article Version)](http://www.niso.org/publications/rp/RP-8-2008.pdf) and, although this terminology is [sometimes problematic](https://f1000research.com/articles/6-608/v1), you should be aware of it. In particualr, you will see two terms used  in Crossref metadata:\n",
     "\n",
     "- `VOR` = Version of Record\n",
     "- `AM` = Accepted Manuscript\n",
@@ -332,7 +332,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "The above has given us a brief overview of how to get a record and elements of a record identified with a Crossref DOI. Obviously, the goald is to do this in bulk. That is, to select and process records for multiple Crossref DOIs. Before we do that, it is helpful to familiarise yourself with some of the other \"routes\" supported by the REST API. This is because more advanced usage of the API typically involveds combining information from several routes. "
+    "The above has given us a brief overview of how to get a record and elements of a record identified with a Crossref DOI. Obviously, the goal is to do this in bulk. That is, to select and process records for multiple Crossref DOIs. Before we do that, it is helpful to familiarise yourself with some of the other \"routes\" supported by the REST API. This is because more advanced usage of the API typically involveds combining information from several routes. "
    ]
   },
   {
@@ -402,7 +402,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "Let's look at a partciularmember, Hindawi:"
+    "Let's look at a partciular member, Hindawi:"
    ]
   },
   {
@@ -867,8 +867,7 @@
    "source": [
     "from crossref.restful import Works\n",
     "works = Works()\n",
-    "zika_sample = [work for work in works.query('zika').sample(10)]\n",
-    "zika_sample"
+    "works.query('zika').url"
    ]
   },
   {
@@ -886,7 +885,8 @@
    "source": [
     "from crossref.restful import Works\n",
     "works = Works()\n",
-    "works.query('zika').url"
+    "zika_sample = [work for work in works.query('zika').sample(10)]\n",
+    "zika_sample"
    ]
   },
   {
@@ -915,7 +915,7 @@
     }
    },
    "source": [
-    "Works records indexed _today_ that have affiliatioon data"
+    "Works records indexed _today_ that have affiliation data"
    ]
   },
   {

From b8f2b16d75c52c3774f460ac6ac74d20b66bcd6e Mon Sep 17 00:00:00 2001
From: Geoffrey Bilder 
Date: Fri, 26 Jan 2018 09:12:50 +0000
Subject: [PATCH 200/219] add info on frequency of indexing

---
 README.md | 8 ++++++++
 1 file changed, 8 insertions(+)

diff --git a/README.md b/README.md
index 55ff0d8..e55c378 100644
--- a/README.md
+++ b/README.md
@@ -28,6 +28,13 @@ The Crossref REST API is one of [a variety of tools and APIs](https://www.crossr
 
 
 ## Meta
+
+### Frequency of indexing
+
+Records typically appear in the REST API within 20 minutes of their having been successfully deposited with Crossref.
+
+Summary information (e.g. counts, etc.) are processed in batch every 24 hours.
+
 ### Learning about performance or availability problems
 
 Note that we generally post notice any ongoing performance problems with our services on our twitter feeds at [CrossrefOrg](https://twitter.com/CrossrefOrg) and [CrossrefSupport](https://twitter.com/@CrossrefSupport). We also report them on our [support site](https://support.crossref.org/hc/en-us). You might want to check these to see if we are already aware of a problem before you report it.
@@ -696,3 +703,4 @@ Each major version has no backwards incompatible changes within its public inter
 - v53, 2017-08-11, mention `full-text.application` filter
 - v54, 2017-09-18, add info about new "polite pool"
 - v55, 2017-09-21, document `/member` and `/funder` filters. document `publisher-name` facet. document `select` parameter.
+- v56, 2018-01-26, add info on frequency of indexing

From 447cdbd0d5f61f256dfe12952d9c3d8076cd38d3 Mon Sep 17 00:00:00 2001
From: Geoffrey Bilder 
Date: Thu, 1 Feb 2018 07:44:54 +0100
Subject: [PATCH 201/219] add ISBN doc

---
 README.md | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/README.md b/README.md
index e55c378..432325e 100644
--- a/README.md
+++ b/README.md
@@ -447,6 +447,7 @@ The following filters are supported for the `/works` route:
 | `has-authenticated-orcid` | | metadata which includes one or more ORCIDs where the depositing publisher claims to have witness the ORCID owner authenticate with ORCID |
 | `orcid` | `{orcid}` | metadata where `` element's value = `{orcid}` |
 | `issn` | `{issn}` | metadata where record has an ISSN = `{issn}`. Format is `xxxx-xxxx`. |
+| `isbn` | `{isbn}` | metadata where record has an ISBN = `{issn}`. |
 | `type` | `{type}` | metadata records whose type = `{type}`. Type must be an ID value from the list of types returned by the `/types` resource |
 | `directory` | `{directory}` | metadata records whose article or serial are mentioned in the given `{directory}`. Currently the only supported value is `doaj`. |
 | `doi` | `{doi}` | metadata describing the DOI `{doi}` |
@@ -704,3 +705,4 @@ Each major version has no backwards incompatible changes within its public inter
 - v54, 2017-09-18, add info about new "polite pool"
 - v55, 2017-09-21, document `/member` and `/funder` filters. document `publisher-name` facet. document `select` parameter.
 - v56, 2018-01-26, add info on frequency of indexing
+- v57, 2018-02-01, document ISBN filter

From 2e966e5eb00f2bb256c76ff8f84f9ede51d8a441 Mon Sep 17 00:00:00 2001
From: Geoffrey Bilder 
Date: Tue, 13 Feb 2018 09:33:44 +0100
Subject: [PATCH 202/219] document reference-visibility filter

---
 README.md | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/README.md b/README.md
index 432325e..b8df336 100644
--- a/README.md
+++ b/README.md
@@ -441,6 +441,7 @@ The following filters are supported for the `/works` route:
 | `full-text.type` | `{mime_type}`  | metadata where `` element's `content_type` attribute is `{mime_type}` (e.g. `application/pdf`). |
 | `full-text.application` | `{string}` | metadata where `` link has one of the following intended applications: `text-mining`, `similarity-checking` or `unspecified` |
 | `has-references` | | metadata for works that have a list of references |
+| `reference-visibility` | `[open, closed, mixed]` | metadata for works where references are either `open`, `closed` or `mixed` |
 | `has-archive` | | metadata which include name of archive partner |
 | `archive` | `{string}` | metadata which where value of archive partner is `{string}` |
 | `has-orcid` | | metadata which includes one or more ORCIDs |
@@ -482,6 +483,7 @@ The following filters are supported for the `/members` route:
 | filter     | possible values | description|
 |:-----------|:----------------|:-----------|
 | `has-public-references` | | Member has made their references public for one or more of their prefixes |
+| `reference-visibility` | `[open, closed, mixed]` | Members who have made their references either `open`, `closed` or `mixed` |
 | `backfile-doi-count` | {integer} | count of DOIs for material published more than two years ago |
 | `current-doi-count` | {integer} | count of DOIs for material published within last two years |
 
@@ -706,3 +708,4 @@ Each major version has no backwards incompatible changes within its public inter
 - v55, 2017-09-21, document `/member` and `/funder` filters. document `publisher-name` facet. document `select` parameter.
 - v56, 2018-01-26, add info on frequency of indexing
 - v57, 2018-02-01, document ISBN filter
+- v58, 2018-02-13, document `reference-visibility` filter for `/works` and `/members` routes

From 35262d8438279fe8e0b5e3336469580c42d51f0a Mon Sep 17 00:00:00 2001
From: Geoffrey Bilder 
Date: Tue, 13 Feb 2018 10:03:49 +0100
Subject: [PATCH 203/219] added info about Mtedata Plus service. Corrected
 spelling. Added example of using  filter.

---
 README.md | 54 +++++++++++++++++++++++++++++++++++++++---------------
 1 file changed, 39 insertions(+), 15 deletions(-)

diff --git a/README.md b/README.md
index b8df336..7ad7bc7 100644
--- a/README.md
+++ b/README.md
@@ -76,7 +76,7 @@ We want to provide a public, open, and free API for all. And we don't want to un
 
 - Cache data so you don't request the same data over and over again.
 - Actively monitor API response times. If they start to go up, back-off for a while. For example, add pauses between requests and/or reduce the number of parallel requests.
-- Specify a `User-Agent` header that properly identifies your script or tool and that provides a means of contacting you vai email using "mailto:". For example:
+- Specify a `User-Agent` header that properly identifies your script or tool and that provides a means of contacting you via email using "mailto:". For example:
 `GroovyBib/1.1 (https://example.org/GroovyBib/; mailto:GroovyBib@example.org) BasedOnFunkyLib/1.4`.
 
 This way we can contact you if we see a problem.
@@ -124,7 +124,7 @@ Note that this only works if you query the API using HTTPS. You really should be
 
 **Q:** Does the contact info have to be a real name?
 
-**A:** No. As long as somebody actually recieves and pays attention to email at the address, it can be pseudoanonymous, or whatever.
+**A:** No. As long as somebody actually receives and pays attention to email at the address, it can be pseudo-anonymous, or whatever.
 
 
 
@@ -140,7 +140,7 @@ But seriously... this is a bummer. We really want you to use the API. If you are
 
 ### Use for production services
 
-What if you want to use our API for a production service that cannot depend on the performance uncertainties of the free and open public API? What if you don't want to be affected by impolite people who do not follow the [API Etiquette](#api-etiquette) guidelines? Well, if you’re interested in using these tools or APIs for production services, we’ll soon have a service-level offering with access to all supported APIs and metadata, but with extra service and support guarantees. If you are interested in the upcoming service-based offering please contact our [outreach team](mailto://member@crossref.org).
+What if you want to use our API for a production service that cannot depend on the performance uncertainties of the free and open public API? What if you don't want to be affected by impolite people who do not follow the [API Etiquette](#api-etiquette) guidelines? Well, if you’re interested in using these tools or APIs for production services, we [have a service-level offering](https://www.crossref.org/services/metadata-delivery/plus-service/) with access to all supported APIs and metadata, but with extra service and support guarantees.
 
 ## API overview
 
@@ -441,7 +441,7 @@ The following filters are supported for the `/works` route:
 | `full-text.type` | `{mime_type}`  | metadata where `` element's `content_type` attribute is `{mime_type}` (e.g. `application/pdf`). |
 | `full-text.application` | `{string}` | metadata where `` link has one of the following intended applications: `text-mining`, `similarity-checking` or `unspecified` |
 | `has-references` | | metadata for works that have a list of references |
-| `reference-visibility` | `[open, closed, mixed]` | metadata for works where references are either `open`, `closed` or `mixed` |
+| `reference-visibility` | `[open, limited, closed]` | metadata for works where references are either `open`, `limited` (to [Metadata Plus subscribers](https://www.crossref.org/services/metadata-delivery/plus-service/)) or `closed` |
 | `has-archive` | | metadata which include name of archive partner |
 | `archive` | `{string}` | metadata which where value of archive partner is `{string}` |
 | `has-orcid` | | metadata which includes one or more ORCIDs |
@@ -483,7 +483,7 @@ The following filters are supported for the `/members` route:
 | filter     | possible values | description|
 |:-----------|:----------------|:-----------|
 | `has-public-references` | | Member has made their references public for one or more of their prefixes |
-| `reference-visibility` | `[open, closed, mixed]` | Members who have made their references either `open`, `closed` or `mixed` |
+| `reference-visibility` | `[open, limited, closed]` | Members who have made their references either `open`, `limited` (to [Metadata Plus subscribers](https://www.crossref.org/services/metadata-delivery/plus-service/)) or `closed` |
 | `backfile-doi-count` | {integer} | count of DOIs for material published more than two years ago |
 | `current-doi-count` | {integer} | count of DOIs for material published within last two years |
 
@@ -586,41 +586,64 @@ Note that when you use the `sample` parameter, the `rows` and `offset` parameter
 
 **All works published by owner prefix `10.1016` in January 2010**
 
-    https://api.crossref.org/prefixes/10.1016/works?filter=from-pub-date:2010-01,until-pub-date:2010-01
+```
+https://api.crossref.org/prefixes/10.1016/works?filter=from-pub-date:2010-01,until-pub-date:2010-01
+```
 
 **All works funded by `10.13039/100000001` that have a CC-BY license**
 
-    https://api.crossref.org/funders/10.13039/100000001/works?filter=license.url:http://creativecommons.org/licenses/by/3.0/
+```
+https://api.crossref.org/funders/10.13039/100000001/works?filter=license.url:http://creativecommons.org/licenses/by/3.0/
+```
 
 **All works published by owner prefix 10.6064 from February 2010 to February 2013 that have a CC-BY license**
 
-    https://api.crossref.org/prefixes/10.6064/works?filter=license.url:http://creativecommons.org/licenses/by/3.0/,from-pub-date:2010-02,until-pub-date:2013-02
+```
+https://api.crossref.org/prefixes/10.6064/works?filter=license.url:http://creativecommons.org/licenses/by/3.0/,from-pub-date:2010-02,until-pub-date:2013-02
+```
 
 **All works funded by `10.13039/100000015` where license = CC-BY and embargo <= 365 days**
 
-    https://api.crossref.org/funders/10.13039/100000015/works?filter=license.url:http://creativecommons.org/licenses/by/3.0/,license.delay:365
-
+```
+https://api.crossref.org/funders/10.13039/100000015/works?filter=license.url:http://creativecommons.org/licenses/by/3.0/,license.delay:365
+```
 Note that the filters for license URL and maximum license embargo period (license.url and license.delay) combine to filter each document's metadata for a license with both of these properties.
 
 **All works where the archive partner listed = 'CLOCKSS'**
 
-    https://api.crossref.org/works?filter=archive:CLOCKSS
+```
+https://api.crossref.org/works?filter=archive:CLOCKSS
+```
 
 **All members with `hind` in their name (e.g. Hindawi)**
 
-    https://api.crossref.org/members?query=hind
+```
+https://api.crossref.org/members?query=hind
+```
 
 **All licenses linked to works published by Elsevier**
 
-    http://api.crossref.org/v1/works?facet=license:*&filter=member:78&rows=0
+```
+http://api.crossref.org/v1/works?facet=license:*&filter=member:78&rows=0
+```
 
 **All licenses applied to works published in the journal `Pathology Research International`**
 
-    https://api.crossref.org/works?facet=license:*&filter=issn:2090-8091
+```
+https://api.crossref.org/works?facet=license:*&filter=issn:2090-8091
+```
 
 **All works with an award numbered roughly `1 F31 MH11745` also awarded by funder with ID `10.13039/100000025`:
 
-    https://api.crossref.org/works?filter=award.number:1F31MH11745,award.funder:10.13039/100000025
+```
+https://api.crossref.org/works?filter=award.number:1F31MH11745,award.funder:10.13039/100000025
+```
+
+** The number of DOIs that have references AND where references are `open` faceted by publisher name **
+
+```
+http://api.crossref.org/v1.0/works?filter=has-references:true,reference-visibility:open&facet=publisher-name:*&rows=0
+```
 
 ## API versioning
 
@@ -709,3 +732,4 @@ Each major version has no backwards incompatible changes within its public inter
 - v56, 2018-01-26, add info on frequency of indexing
 - v57, 2018-02-01, document ISBN filter
 - v58, 2018-02-13, document `reference-visibility` filter for `/works` and `/members` routes
+- v59, 2018-02,13, added info about Mtedata Plus service. Corrected spelling. Added example of using `reference-visibility` filter.

From bb23e67409bf316f53a85d0b55bda427b3a0e0f7 Mon Sep 17 00:00:00 2001
From: MikeYalter 
Date: Wed, 14 Feb 2018 14:04:36 -0500
Subject: [PATCH 204/219] has-domain-restriction instead of
 has-crossmark-restriction

---
 README.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/README.md b/README.md
index 7ad7bc7..ed4d477 100644
--- a/README.md
+++ b/README.md
@@ -471,7 +471,7 @@ The following filters are supported for the `/works` route:
 | `has-clinical-trial-number` | | metadata for records which include a clinical trial number |
 | `content-domain` | | metadata where the publisher records a particular domain name as the location Crossmark content will appear |
 | `has-content-domain` | | metadata where the publisher records a domain name location for Crossmark content |
-| `has-crossmark-restriction` | | metadata where the publisher restricts Crossmark usage to content domains |
+| `has-domain-restriction` | | metadata where the publisher restricts Crossmark usage to content domains |
 | `has-relation` | | metadata for records that either assert or are the object of a relation |
 | `relation.type` | | One of the relation types from the Crossref relations schema (e.g. `is-referenced-by`, `is-parent-of`, `is-preprint-of`) |
 | `relation.object` | | Relations where the object identifier matches the identifier provided |

From 83e06e88cea7522765f443d3cd427f3ec3ce41ba Mon Sep 17 00:00:00 2001
From: Geoffrey Bilder 
Date: Thu, 22 Feb 2018 08:32:38 +0100
Subject: [PATCH 205/219] add info for plus users on use of Authorization
 header for token

---
 README.md | 7 +++++--
 1 file changed, 5 insertions(+), 2 deletions(-)

diff --git a/README.md b/README.md
index 7ad7bc7..15195da 100644
--- a/README.md
+++ b/README.md
@@ -140,7 +140,9 @@ But seriously... this is a bummer. We really want you to use the API. If you are
 
 ### Use for production services
 
-What if you want to use our API for a production service that cannot depend on the performance uncertainties of the free and open public API? What if you don't want to be affected by impolite people who do not follow the [API Etiquette](#api-etiquette) guidelines? Well, if you’re interested in using these tools or APIs for production services, we [have a service-level offering](https://www.crossref.org/services/metadata-delivery/plus-service/) with access to all supported APIs and metadata, but with extra service and support guarantees.
+What if you want to use our API for a production service that cannot depend on the performance uncertainties of the free and open public API? What if you don't want to be affected by impolite people who do not follow the [API Etiquette](#api-etiquette) guidelines? Well, if you’re interested in using these tools or APIs for production services, we [have a service-level offering](https://www.crossref.org/services/metadata-delivery/plus-service/) called "Plus". This service provides you with with access to all supported APIs and metadata, but with extra service and support guarantees.
+
+When you sign up for the Plus service, you will be issued an API token that you should put in the `Authorization` header of all your rest API requests. This token will ensure that said requests get directed to a pool of machines that are reserved for "Plus" SLA users.
 
 ## API overview
 
@@ -732,4 +734,5 @@ Each major version has no backwards incompatible changes within its public inter
 - v56, 2018-01-26, add info on frequency of indexing
 - v57, 2018-02-01, document ISBN filter
 - v58, 2018-02-13, document `reference-visibility` filter for `/works` and `/members` routes
-- v59, 2018-02,13, added info about Mtedata Plus service. Corrected spelling. Added example of using `reference-visibility` filter.
+- v59, 2018-02-13, added info about Mtedata Plus service. Corrected spelling. Added example of using `reference-visibility` filter.
+- v60, 2018-02-22, added info for "Plus" users on use of toekn in `Authorization` header.
\ No newline at end of file

From a415e2e61cc7663f0499123e90fe18994090a304 Mon Sep 17 00:00:00 2001
From: Geoffrey Bilder 
Date: Thu, 22 Feb 2018 08:37:46 +0100
Subject: [PATCH 206/219] formatting

---
 README.md | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/README.md b/README.md
index ea17f43..ea14b34 100644
--- a/README.md
+++ b/README.md
@@ -142,6 +142,8 @@ But seriously... this is a bummer. We really want you to use the API. If you are
 
 What if you want to use our API for a production service that cannot depend on the performance uncertainties of the free and open public API? What if you don't want to be affected by impolite people who do not follow the [API Etiquette](#api-etiquette) guidelines? Well, if you’re interested in using these tools or APIs for production services, we [have a service-level offering](https://www.crossref.org/services/metadata-delivery/plus-service/) called "Plus". This service provides you with with access to all supported APIs and metadata, but with extra service and support guarantees.
 
+#### Authorization token for Plus service
+
 When you sign up for the Plus service, you will be issued an API token that you should put in the `Authorization` header of all your rest API requests. This token will ensure that said requests get directed to a pool of machines that are reserved for "Plus" SLA users.
 
 ## API overview
@@ -735,4 +737,4 @@ Each major version has no backwards incompatible changes within its public inter
 - v57, 2018-02-01, document ISBN filter
 - v58, 2018-02-13, document `reference-visibility` filter for `/works` and `/members` routes
 - v59, 2018-02-13, added info about Mtedata Plus service. Corrected spelling. Added example of using `reference-visibility` filter.
-- v60, 2018-02-22, added info for "Plus" users on use of toekn in `Authorization` header.
\ No newline at end of file
+- v60, 2018-02-22, added info for "Plus" users on use of toekn in `Authorization` header.

From c4650fcb20d469278367a19b228e5050f47aae4d Mon Sep 17 00:00:00 2001
From: Geoffrey Bilder 
Date: Mon, 26 Feb 2018 13:15:44 +0100
Subject: [PATCH 207/219] add token example with curl

---
 README.md | 14 ++++++++++++--
 1 file changed, 12 insertions(+), 2 deletions(-)

diff --git a/README.md b/README.md
index ea14b34..a80d666 100644
--- a/README.md
+++ b/README.md
@@ -144,7 +144,16 @@ What if you want to use our API for a production service that cannot depend on t
 
 #### Authorization token for Plus service
 
-When you sign up for the Plus service, you will be issued an API token that you should put in the `Authorization` header of all your rest API requests. This token will ensure that said requests get directed to a pool of machines that are reserved for "Plus" SLA users.
+When you sign up for the Plus service, you will be issued an API token that you should put in the `Authorization` header of all your rest API requests. This token will ensure that said requests get directed to a pool of machines that are reserved for "Plus" SLA users. For example, with [curl](https://curl.haxx.se/):
+
+```
+curl -X GET \
+  https://api.crossref.org/works \
+  -H 'Authorization: Bearer yJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJodHRwOi8vY3Jvc3NyZWYub3JnLyIsImF1ZXYZImVuaGFuY2VkY21zIiwianRpIjoiN0M5ODlFNTItMTFEQS00QkY3LUJCRUUtODFCMUM3QzE0OTZEIn0.NYe3-O066sce9R1fjMzNEvP88VqSEaYdBY622FDiG8Uq' \
+  -H 'User-Agent: GroovyBib/1.1 (https://example.org/GroovyBib/; mailto:GroovyBib@example.org) BasedOnFunkyLib/1.4'
+  ```
+
+Note that you can still be "polite" and identify yourself as well. And, of course, replace the fake token above with the real token.
 
 ## API overview
 
@@ -737,4 +746,5 @@ Each major version has no backwards incompatible changes within its public inter
 - v57, 2018-02-01, document ISBN filter
 - v58, 2018-02-13, document `reference-visibility` filter for `/works` and `/members` routes
 - v59, 2018-02-13, added info about Mtedata Plus service. Corrected spelling. Added example of using `reference-visibility` filter.
-- v60, 2018-02-22, added info for "Plus" users on use of toekn in `Authorization` header.
+- v60, 2018-02-22, added info for "Plus" users on use of token in `Authorization` header.
+- v61, 2018-02-26, add curl example for use of token.

From 5b357d9178619925931e4cdf5c5a00ec04fbad2c Mon Sep 17 00:00:00 2001
From: Geoffrey Bilder 
Date: Wed, 25 Apr 2018 12:21:56 +0200
Subject: [PATCH 208/219] fix typo

---
 README.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/README.md b/README.md
index a80d666..4e4750c 100644
--- a/README.md
+++ b/README.md
@@ -522,7 +522,7 @@ would locate documents that are updates, were published on or after 3rd March 20
 
 ### Dot filters
 
-A filter with a dot in its name is special. The dot signifies that the filter will be applied to some other record type that is related to primary resource record type. For example, with work queries, one can filter on works that have an award, where the same award has a particular award number and award-gving funding agency:
+A filter with a dot in its name is special. The dot signifies that the filter will be applied to some other record type that is related to primary resource record type. For example, with work queries, one can filter on works that have an award, where the same award has a particular award number and award-giving funding agency:
 
     /works?filter=award.number:CBET-0756451,award.funder:10.13039/100000001
 

From cbcd0987c7226c4070d3c1052030ebc50128e4fc Mon Sep 17 00:00:00 2001
From: jenniferlin15 
Date: Tue, 15 May 2018 07:04:07 -0700
Subject: [PATCH 209/219] Adding peer review elements

---
 api_format.md | 15 +++++++++++++++
 1 file changed, 15 insertions(+)

diff --git a/api_format.md b/api_format.md
index e8c89f6..0adaacf 100644
--- a/api_format.md
+++ b/api_format.md
@@ -6,6 +6,7 @@
 |---------|--------------|----------|
 | v1 | 11th July 2016 | First documented version |
 | v2 | 26th July 2017 | Add abstract, authenticated-orcid, fix contributor fields |
+| v3 | 15th May 2018 | Add peer review fields |
 
 ## Work
 
@@ -61,6 +62,7 @@
 | reference | Array of [Reference](#reference) | No | List of references made by the work |
 | content-domain | [Content Domain](#content-domain) | No | Information on domains that support Crossmark for this work |
 | relation | [Relations](#relations) | No | Relations to other works |
+| review | [Review](#review) | No | Peer review metadata |
 
 
 ## Work Nested Types
@@ -209,3 +211,16 @@ A hashmap containing relation name, [Relation](#relation) pairs.
 | id-type | String | Yes | |
 | id | String | Yes | |
 | asserted-by | String | Yes | One of `subject` or `object` |
+
+
+### Review
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| running-number | String | Yes | |
+| revision-round | String | Yes | |
+| stage | String | Yes | One of `pre-publication` or `post-publication` |
+| recommendation | String | Yes | One of `major-revision` or `minor-revision` or `reject` or `reject-with-resubmit` or `accept` |
+| type | String | Yes | One of `referee-report` or `editor-report` or `author-comment` or `community-comment` or `aggregate` |
+| competing-interest-statement | String | Yes | |
+| language | String | Yes | |

From c4bf9605e8a8484a22551a5a82b62f3815b590c3 Mon Sep 17 00:00:00 2001
From: jenniferlin15 
Date: Tue, 15 May 2018 07:08:59 -0700
Subject: [PATCH 210/219] Update api_format.md

---
 api_format.md | 14 +++++++-------
 1 file changed, 7 insertions(+), 7 deletions(-)

diff --git a/api_format.md b/api_format.md
index 0adaacf..931f834 100644
--- a/api_format.md
+++ b/api_format.md
@@ -217,10 +217,10 @@ A hashmap containing relation name, [Relation](#relation) pairs.
 
 | Field | Type | Required | Description |
 |-------|------|----------|-------------|
-| running-number | String | Yes | |
-| revision-round | String | Yes | |
-| stage | String | Yes | One of `pre-publication` or `post-publication` |
-| recommendation | String | Yes | One of `major-revision` or `minor-revision` or `reject` or `reject-with-resubmit` or `accept` |
-| type | String | Yes | One of `referee-report` or `editor-report` or `author-comment` or `community-comment` or `aggregate` |
-| competing-interest-statement | String | Yes | |
-| language | String | Yes | |
+| running-number | String | No | |
+| revision-round | String | No | |
+| stage | String | No | One of `pre-publication` or `post-publication` |
+| recommendation | String | No | One of `major-revision` or `minor-revision` or `reject` or `reject-with-resubmit` or `accept` |
+| type | String | No | One of `referee-report` or `editor-report` or `author-comment` or `community-comment` or `aggregate` |
+| competing-interest-statement | String | No | |
+| language | String | No | |

From af2b282fd1bcfa6363ea2363bf35e4e9d56b182d Mon Sep 17 00:00:00 2001
From: Geoffrey Bilder 
Date: Mon, 18 Jun 2018 10:04:15 +0200
Subject: [PATCH 211/219] clarify rate limits

---
 README.md | 16 ++++++++++++++++
 1 file changed, 16 insertions(+)

diff --git a/README.md b/README.md
index 4e4750c..71d4955 100644
--- a/README.md
+++ b/README.md
@@ -132,6 +132,21 @@ Note that this only works if you query the API using HTTPS. You really should be
 
 From time to time Crossref needs to impose rate limits to ensure that the free API is usable by all. Any rate limits that are in effect will be advertised in the `X-Rate-Limit-Limit` and `X-Rate-Limit-Interval` HTTP headers.
 
+For ease-of-parsing, the `X-Rate-Limit-Interval` will always be expressed in seconds. So, for example the following tells you that you should expect to be able to perform 50 requests a second:
+
+```
+`X-Rate-Limit-Limit`: 50
+`X-Rate-Limit-Interval`: 1s
+```
+
+Note that if we wanted to adjust the measurement window, we could specify:
+
+```
+`X-Rate-Limit-Limit`: 3000
+`X-Rate-Limit-Interval`: 60s
+```
+
+
 #### Blocking
 
 This is always our last resort, and you can generally avoid it if you include contact information in the `User-Agent` header or `mailto` parameter as described above.
@@ -748,3 +763,4 @@ Each major version has no backwards incompatible changes within its public inter
 - v59, 2018-02-13, added info about Mtedata Plus service. Corrected spelling. Added example of using `reference-visibility` filter.
 - v60, 2018-02-22, added info for "Plus" users on use of token in `Authorization` header.
 - v61, 2018-02-26, add curl example for use of token.
+- v62, 2018-06-18, clarify how to parse `X-Rate-Limit-Limit-Interval`

From 14c6473ce0f85d51d80e981bb8fec2d468ede3d0 Mon Sep 17 00:00:00 2001
From: Geoffrey Bilder 
Date: Thu, 16 Aug 2018 08:21:43 +0200
Subject: [PATCH 212/219] remove mistakenly listed year facet.

---
 README.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/README.md b/README.md
index 71d4955..7edb1b9 100644
--- a/README.md
+++ b/README.md
@@ -411,7 +411,6 @@ Facets are specified with the `facet` parameter:
 | Facet name | Maximum values | Description |
 |:-----------|:---------------|-------------|
 | `affiliation` | `*` | Author affiliation |
-| `year` | `*` | Earliest year of publication, synonym for `published` |
 | `funder-name` | `*` | Funder literal name as deposited alongside DOIs |
 | `funder-doi` | `*` | Funder DOI |
 | `orcid` | 100 | Contributor ORCID |
@@ -764,3 +763,4 @@ Each major version has no backwards incompatible changes within its public inter
 - v60, 2018-02-22, added info for "Plus" users on use of token in `Authorization` header.
 - v61, 2018-02-26, add curl example for use of token.
 - v62, 2018-06-18, clarify how to parse `X-Rate-Limit-Limit-Interval`
+- v63, 2018-08-16, remove mistakenly listed `year` facet. `published` is correct facet name.

From bbfa7b24f4a8885b4d08af2d09753081fbc71270 Mon Sep 17 00:00:00 2001
From: Daniel Mietchen 
Date: Sun, 26 Aug 2018 04:16:06 +0200
Subject: [PATCH 213/219] copyedit

---
 README.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/README.md b/README.md
index 7edb1b9..eb03615 100644
--- a/README.md
+++ b/README.md
@@ -37,7 +37,7 @@ Summary information (e.g. counts, etc.) are processed in batch every 24 hours.
 
 ### Learning about performance or availability problems
 
-Note that we generally post notice any ongoing performance problems with our services on our twitter feeds at [CrossrefOrg](https://twitter.com/CrossrefOrg) and [CrossrefSupport](https://twitter.com/@CrossrefSupport). We also report them on our [support site](https://support.crossref.org/hc/en-us). You might want to check these to see if we are already aware of a problem before you report it.
+Note that we generally post notice of any ongoing performance problems with our services on our twitter feeds at [CrossrefOrg](https://twitter.com/CrossrefOrg) and [CrossrefSupport](https://twitter.com/@CrossrefSupport). We also report them on our [support site](https://support.crossref.org/hc/en-us). You might want to check these to see if we are already aware of a problem before you report it.
 
 ### Reporting performance or availability problems
 

From 7478094d0924950a3db3cb4e09984c313f7dc6d0 Mon Sep 17 00:00:00 2001
From: Geoffrey Bilder 
Date: Tue, 4 Sep 2018 13:25:42 +0200
Subject: [PATCH 214/219] add info about status page

---
 README.md | 7 ++++++-
 1 file changed, 6 insertions(+), 1 deletion(-)

diff --git a/README.md b/README.md
index eb03615..f152ec2 100644
--- a/README.md
+++ b/README.md
@@ -37,7 +37,11 @@ Summary information (e.g. counts, etc.) are processed in batch every 24 hours.
 
 ### Learning about performance or availability problems
 
-Note that we generally post notice of any ongoing performance problems with our services on our twitter feeds at [CrossrefOrg](https://twitter.com/CrossrefOrg) and [CrossrefSupport](https://twitter.com/@CrossrefSupport). We also report them on our [support site](https://support.crossref.org/hc/en-us). You might want to check these to see if we are already aware of a problem before you report it.
+We record and report service issues on our [status page](http://status.crossref.org).
+
+You might want to check this to see if we are already aware of a problem before you report it.
+
+We also post notice of any ongoing performance problems with our services on our twitter feeds at [CrossrefOrg](https://twitter.com/CrossrefOrg) and [CrossrefSupport](https://twitter.com/@CrossrefSupport).
 
 ### Reporting performance or availability problems
 
@@ -764,3 +768,4 @@ Each major version has no backwards incompatible changes within its public inter
 - v61, 2018-02-26, add curl example for use of token.
 - v62, 2018-06-18, clarify how to parse `X-Rate-Limit-Limit-Interval`
 - v63, 2018-08-16, remove mistakenly listed `year` facet. `published` is correct facet name.
+- v64, 2018-09-04, add text and link to status page.

From 00cbcbf0577af82acdaf08aa0a2c8a9ed9880e32 Mon Sep 17 00:00:00 2001
From: Daniel Mietchen 
Date: Mon, 24 Sep 2018 03:05:12 +0200
Subject: [PATCH 215/219] typo fix

---
 README.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/README.md b/README.md
index f152ec2..8ade27e 100644
--- a/README.md
+++ b/README.md
@@ -159,7 +159,7 @@ But seriously... this is a bummer. We really want you to use the API. If you are
 
 ### Use for production services
 
-What if you want to use our API for a production service that cannot depend on the performance uncertainties of the free and open public API? What if you don't want to be affected by impolite people who do not follow the [API Etiquette](#api-etiquette) guidelines? Well, if you’re interested in using these tools or APIs for production services, we [have a service-level offering](https://www.crossref.org/services/metadata-delivery/plus-service/) called "Plus". This service provides you with with access to all supported APIs and metadata, but with extra service and support guarantees.
+What if you want to use our API for a production service that cannot depend on the performance uncertainties of the free and open public API? What if you don't want to be affected by impolite people who do not follow the [API Etiquette](#api-etiquette) guidelines? Well, if you’re interested in using these tools or APIs for production services, we [have a service-level offering](https://www.crossref.org/services/metadata-delivery/plus-service/) called "Plus". This service provides you with access to all supported APIs and metadata, but with extra service and support guarantees.
 
 #### Authorization token for Plus service
 

From 61d2131167638481648a2f38832fb2500ff55f26 Mon Sep 17 00:00:00 2001
From: refraction-ray 
Date: Wed, 28 Nov 2018 16:20:40 +0800
Subject: [PATCH 216/219] typo and md syntax

---
 README.md | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/README.md b/README.md
index 8ade27e..ffffeb1 100644
--- a/README.md
+++ b/README.md
@@ -170,7 +170,7 @@ curl -X GET \
   https://api.crossref.org/works \
   -H 'Authorization: Bearer yJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJodHRwOi8vY3Jvc3NyZWYub3JnLyIsImF1ZXYZImVuaGFuY2VkY21zIiwianRpIjoiN0M5ODlFNTItMTFEQS00QkY3LUJCRUUtODFCMUM3QzE0OTZEIn0.NYe3-O066sce9R1fjMzNEvP88VqSEaYdBY622FDiG8Uq' \
   -H 'User-Agent: GroovyBib/1.1 (https://example.org/GroovyBib/; mailto:GroovyBib@example.org) BasedOnFunkyLib/1.4'
-  ```
+```
 
 Note that you can still be "polite" and identify yourself as well. And, of course, replace the fake token above with the real token.
 
@@ -330,7 +330,7 @@ Parameters can be used to query, filter and control the results returned by the
 | `query`                      | query terms |
 | `filter={filter_name}:{value}`| filter results by specific fields |
 | `rows={#}`                   | results per per page |
-| `offset={#}` (mak 10k)               | result offset (user `cursor` for larger `/works` result sets)  |                         
+| `offset={#}` (max 10k)               | result offset (user `cursor` for larger `/works` result sets)  |
 | `sample={#}` (max 100)                | return random N results |
 | `sort={#}`                   | sort results by a certain field |
 | `order={#}`                  | set the sort order to `asc` or `desc` |
@@ -664,13 +664,13 @@ http://api.crossref.org/v1/works?facet=license:*&filter=member:78&rows=0
 https://api.crossref.org/works?facet=license:*&filter=issn:2090-8091
 ```
 
-**All works with an award numbered roughly `1 F31 MH11745` also awarded by funder with ID `10.13039/100000025`:
+**All works with an award numbered roughly `1 F31 MH11745` also awarded by funder with ID `10.13039/100000025`**
 
 ```
 https://api.crossref.org/works?filter=award.number:1F31MH11745,award.funder:10.13039/100000025
 ```
 
-** The number of DOIs that have references AND where references are `open` faceted by publisher name **
+**The number of DOIs that have references AND where references are `open` faceted by publisher name**
 
 ```
 http://api.crossref.org/v1.0/works?filter=has-references:true,reference-visibility:open&facet=publisher-name:*&rows=0

From 965371c0fea29e14c9410976fe576f59fa7c500c Mon Sep 17 00:00:00 2001
From: Joe Wass 
Date: Wed, 22 May 2019 09:44:12 +0100
Subject: [PATCH 217/219] Clarification on cursor

---
 README.md | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/README.md b/README.md
index ffffeb1..f236849 100644
--- a/README.md
+++ b/README.md
@@ -596,10 +596,12 @@ Using large `offset` values can result in extremely long response times. Offsets
 
     https://api.crossref.org/members/311/works?filter=type:journal-article&cursor=*
 
-A `next-cursor` field will be provided in the JSON response. To get the next page of results, pass the value of `next-cursor` as the `cursor` parameter:
+A `next-cursor` field will be provided in the JSON response. To get the next page of results, pass the value of `next-cursor` as the `cursor` parameter. For example:
 
     https://api.crossref.org/members/311/works?filter=type:journal-article&cursor=AoE/CGh0dHA6Ly9keC5kb2kub3JnLzEwLjEwMDIvdGRtX2xpY2Vuc2VfMQ==
 
+Note that the actual cursor value will be different from this illustration.
+
 Clients should check the number of returned items. If the number of returned items is fewer than the number of expected rows then the end of the result set has been reached. Using `next-cursor` beyond this point will result in responses with an empty items list.
 
 The `cursor` parameter is available on all `/works` resources.

From 6c8c3bdcabaaa397fc41cafeebb9fa60f1cf4c57 Mon Sep 17 00:00:00 2001
From: Dominika Tkaczyk 
Date: Thu, 20 Jun 2019 10:58:22 +0200
Subject: [PATCH 218/219] s/from-first-deposit-date/from-created-date/

---
 README.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/README.md b/README.md
index f236849..fa4c833 100644
--- a/README.md
+++ b/README.md
@@ -560,7 +560,7 @@ Note that dates in filters should always be of the form `YYYY-MM-DD`, `YYYY-MM`
 
 When using time filters to retrieve periodic, incremental metadata updates,
 the `from-index-date` filter should be used over `from-update-date`,
-`from-deposit-date`, `from-first-deposit-date` and `from-pub-date`. The
+`from-deposit-date`, `from-created-date` and `from-pub-date`. The
 timestamp that `from-index-date` filters on is guaranteed to be updated
 every time there is a change to metadata requiring a reindex.
 

From fa1421463f2c27ff573e91ef95c5127e6fa3db3b Mon Sep 17 00:00:00 2001
From: Dominika Tkaczyk 
Date: Thu, 20 Jun 2019 12:41:03 +0200
Subject: [PATCH 219/219] add new library

---
 README.md | 1 +
 1 file changed, 1 insertion(+)

diff --git a/README.md b/README.md
index fa4c833..413cbc1 100644
--- a/README.md
+++ b/README.md
@@ -67,6 +67,7 @@ We also have a [privacy policy](https://www.crossref.org/privacy/).
 
 You might be able to avoid reading all this documentation if you instead use one of the several excellent libraries that have been written for the Crossref REST API. For example:
 
+- [crossref-commons](https://gitlab.com/crossref/crossref_commons_py) (Python, developed by Crossref)
 - [habanero](https://github.com/sckott/habanero) (Python)
 - [serrano](https://github.com/sckott/serrano) (Ruby)
 - [rcrossref](https://github.com/ropensci/rcrossref) (R)