| Both sides previous revisionPrevious revision | Last revisionBoth sides next revision |
| dev:web_api:v3:read_requests [2014/06/12 04:07] – old revision restored dstillman | dev:web_api:v3:read_requests [2014/06/12 05:49] – dstillman |
|---|
| <html><p style="color:red; font-weight:bold">This is draft documentation. APIv3 is not yet available for use.</p></html> | <html><p style="color:red; font-weight:bold">This is draft documentation. APIv3 is not yet available for use.</p></html> |
| |
| ====== Zotero API Read Requests ====== | ====== Zotero API Reference ====== |
| |
| **This is not currently the default [[read_requests#api_versioning|version]] of the API. Include the ''Zotero-API-Version: 3'' HTTP header or the ''v=3'' query parameter to access this version.** | **This is not currently the default [[read_requests#api_versioning|version]] of the API. Include the ''Zotero-API-Version: 3'' HTTP header or the ''v=3'' query parameter to access this version.** |
| |
| The API version of a response will be returned in the ''Zotero-API-Version'' response header. | The API version of a response will be returned in the ''Zotero-API-Version'' response header. |
| | |
| ===== Authentication ===== | ===== Authentication ===== |
| |
| Use of the ''Authentication'' header is recommended, as it will allow use of URLs returned from the API (e.g., for pagination) without modification. | Use of the ''Authentication'' header is recommended, as it will allow use of URLs returned from the API (e.g., for pagination) without modification. |
| |
| ===== GET Requests ===== | ===== Resources ===== |
| | |
| | ==== User and Group Library URLs ==== |
| |
| Requests for data in a specific library begin with ''/users/<userID>'' or ''/groups/<groupID>''. User IDs are different from usernames and can be found on the [[/settings/keys|API Keys]] page and in OAuth responses. | Requests for data in a specific library begin with ''/users/<userID>'' or ''/groups/<groupID>''. User IDs are different from usernames and can be found on the [[/settings/keys|API Keys]] page and in OAuth responses. |
| ==== Requests for "/users/<userID>" or "/groups/<groupID>" ==== | |
| |
| ^ URI ^ Description ^ | ^ URI ^ Description ^ |
| | <userOrGroupPrefix>/searches/<searchKey> | A specific saved search in the library | | | <userOrGroupPrefix>/searches/<searchKey> | A specific saved search in the library | |
| |
| ==== Requests Specific to "/users/<userID>" ==== | ==== User-Only URLs ==== |
| |
| |< 100% 30% >| | |< 100% 30% >| |
| | /users/<userID>/keys/<key> | The privileges of the given API key. | | | /users/<userID>/keys/<key> | The privileges of the given API key. | |
| |
| ===== URL Parameters ===== | ===== Read Requests ===== |
| |
| All parameters are optional. | The following parameters affect the format of data returned from read requests. All parameters are optional. |
| |
| ==== General Parameters ==== | ==== General Parameters ==== |
| |
| The following parameters are valid for all requests: | The following parameters are valid for all read requests: |
| |
| ^ Parameter ^ Values ^ Default ^ Description ^ | ^ Parameter ^ Values ^ Default ^ Description ^ |
| | ''format'' | ''atom'', ''bib'', ''json'', ''keys'', ''versions'', [[#export_formats|export format]] | ''json'' | ''atom'' will return an Atom feed suitable for use in feed readers or feed-reading libraries.\\ ''bib'', valid only for item requests, will return a formatted bibliography as XHTML. ''bib'' mode is currently limited to a maximum of 150 items.\\ ''json'' will return a JSON array for multi-object requests and a single JSON object for single-object requests.\\ ''keys'', valid for multi-object requests, will return a newline-separated list of object keys. ''keys'' mode has no default or maximum limit.\\ ''versions'', valid for multi-object collection, item, search, and tag requests, will return a JSON object with Zotero object keys as keys and object versions as values. Like ''keys'', ''versions'' mode has no default or maximum limit. \\ Export formats, valid only for item requests, produce output in the specified format. | | | ''format'' | ''atom'', ''bib'', ''json'', ''keys'', ''versions'', [[#export_formats|export format]] | ''json'' | ''atom'' will return an Atom feed suitable for use in feed readers or feed-reading libraries.\\ ''bib'', valid only for item requests, will return a formatted bibliography as XHTML. ''bib'' mode is currently limited to a maximum of 150 items.\\ ''json'' will return a JSON array for multi-object requests and a single JSON object for single-object requests.\\ ''keys'', valid for multi-object requests, will return a newline-separated list of object keys. ''keys'' mode has no default or maximum limit.\\ ''versions'', valid for multi-object collection, item, search, and tag requests, will return a JSON object with Zotero object keys as keys and object versions as values. Like ''keys'', ''versions'' mode has no default or maximum limit. \\ Export formats, valid only for item requests, produce output in the specified format. | |
| | |
| | ==== Parameters for "format=json" ==== |
| | |
| | ^ Parameter ^ Values ^ Default ^ Description ^ |
| | | ''include'' | ''bib'', ''data'', [[#export_formats|export format]]\\ Multiple formats can be specified by using a comma as the delimiter (''include=data,bib''). | ''data'' | Formats to include in the response:\\ ''bib'', valid only for item requests, will return a formatted reference for each item.\\ ''data'' (the default) will include all writeable fields in JSON format, suitable for modifying and sending back to the API.\\ Export formats, valid only for item requests, will return data in the specified format for each item. | |
| | |
| | ==== Parameters for "format=atom" ==== |
| | |
| | ^ Parameter ^ Values ^ Default ^ Description ^ |
| | | ''content'' | ''bib'', ''html'', ''json'', [[#export_formats|export formats]], ''none''\\ Multiple formats can be specified by using a comma as the delimiter (''content=json,bib''). | ''html'' | The format of the Atom response's ''<content>'' node:\\ ''html'' (the default) will return an XHTML representation of each object, useful for display in feed readers and for parsing by XML tools.\\ ''json'', currently valid only for item and collection requests, will return a JSON representation of all the item's fields.\\ ''bib'', valid only for item requests, will return a formatted reference for each item.\\ Export formats, valid only for item requests, will return data in the specified format for each item.\\ If additional data is not required, use ''none'' to decrease the response size.\\ If multiple formats are requested, ''<content>'' will contain multiple ''<zapi:subcontent>'' elements (in the %%http://zotero.org/ns/api%% namespace), each with a ''zapi:type'' attribute matching one of the specified content parameters. | |
| | |
| | ==== Parameters for "format=bib" and "content=bib" ==== |
| | |
| | ^ Parameter ^ Values ^ Default ^ Description ^ |
| | | ''style'' | string | ''chicago-note-bibliography'' | Citation style to use for formatted references. Should be the file name (without the .csl extension) of one of the default styles in the Zotero Style Repository (e.g., ''apa'' for https://www.zotero.org/styles/apa). Support for other styles is forthcoming.| |
| | |
| | Note the difference between ''format=bib'' and ''content=bib''. ''format=bib'' returns a formatted bibliography as XHTML, sorted according to the rules of the selected style. ''content=bib'' (valid only for ''format=atom'', the default format mode) returns an individual formatted reference within the Atom ''<content>'' block for each item, with the Atom feed sorted according to the query parameters. ''format=bib'' processes the entire feed you are requesting without regard for any limit arguments, so it is generally a good idea to use it only with collections or tags. |
| | |
| | ==== Export Formats ==== |
| | |
| | The following bibliographic data formats can be used as ''format'', ''include'', and ''content'' parameters: |
| | |
| | ^ Parameter ^ Description ^ |
| | | ''bibtex'' | BibTeX | |
| | | ''bookmarks'' | Netscape Bookmark File Format | |
| | | ''coins'' | COinS | |
| | | ''csljson'' | [[https://github.com/citation-style-language/schema/blob/master/csl-data.json|Citation Style Language data format]] | |
| | | ''mods'' | MODS | |
| | | ''refer'' | Refer/BibIX | |
| | | ''rdf_bibliontology'' | [[http://bibliontology.com/|Bibliographic Ontology]] RDF | |
| | | ''rdf_dc'' | Unqualified Dublin Core RDF | |
| | | ''rdf_zotero'' | Zotero RDF | |
| | | ''ris'' | RIS | |
| | | ''tei'' | Text Encoding Initiative (TEI) | |
| | | ''wikipedia'' | Wikipedia Citation Templates | |
| | |
| | |
| | ===== Searching ===== |
| |
| ==== Search Parameters ==== | ==== Search Parameters ==== |
| |
| |
| ==== Sorting and Pagination ==== | ===== Sorting and Pagination ===== |
| |
| The following parameters are valid only for multi-object requests such as ''/users/123/items'', with the exception of ''format=bib'' requests, which do not support sorting or pagination. | ==== Sorting and Pagination Parameters ==== |
| | |
| | The following parameters are valid only for multi-object read requests such as ''<userOrGroupPrefix>/items'', with the exception of ''format=bib'' requests, which do not support sorting or pagination. |
| |
| ^ Parameter ^ Values ^ Default ^ Description ^ | ^ Parameter ^ Values ^ Default ^ Description ^ |
| | ''start'' | integer | ''0'' | The index of the first result. Combine with the limit parameter to select a slice of the available results. | | | ''start'' | integer | ''0'' | The index of the first result. Combine with the limit parameter to select a slice of the available results. | |
| |
| ==== Parameters for "format=json" ==== | === Total Results === |
| |
| ^ Parameter ^ Values ^ Default ^ Description ^ | Responses for multi-object read requests will include a custom HTTP header, ''Total-Results'', that provides the total number of results matched by the request. The actual number of results provided in a given response will be less than 100. |
| | ''include'' | ''bib'', ''data'', [[#export_formats|export format]]\\ Multiple formats can be specified by using a comma as the delimiter (''include=data,bib''). | ''data'' | Formats to include in the response:\\ ''bib'', valid only for item requests, will return a formatted reference for each item.\\ ''data'' (the default) will include all writeable fields in JSON format, suitable for modifying and sending back to the API.\\ Export formats, valid only for item requests, will return data in the specified format for each item. | | |
| |
| ==== Parameters for "format=atom" ==== | === Link Header === |
| |
| ^ Parameter ^ Values ^ Default ^ Description ^ | When the total number of results matched by a read request is greater than the current limit, the API will include pagination links in the HTTP ''Link'' header. Possible values are ''rel=first'', ''rel=prev'', ''rel=next'', and ''rel=last''. For some requests, the header may also include a ''rel=alternate'' link for the relevant page on the Zotero website. |
| | ''content'' | ''bib'', ''html'', ''json'', [[#export_formats|export formats]], ''none''\\ Multiple formats can be specified by using a comma as the delimiter (''content=json,bib''). | ''html'' | The format of the Atom response's ''<content>'' node:\\ ''html'' (the default) will return an XHTML representation of each object, useful for display in feed readers and for parsing by XML tools.\\ ''json'', currently valid only for item and collection requests, will return a JSON representation of all the item's fields.\\ ''bib'', valid only for item requests, will return a formatted reference for each item.\\ Export formats, valid only for item requests, will return data in the specified format for each item.\\ If additional data is not required, use ''none'' to decrease the response size.\\ If multiple formats are requested, ''<content>'' will contain multiple ''<zapi:subcontent>'' elements (in the %%http://zotero.org/ns/api%% namespace), each with a ''zapi:type'' attribute matching one of the specified content parameters. | | |
| |
| ==== Parameters for "format=bib" and "content=bib" ==== | <code> |
| | GET https://api.zotero.org/users/12345/items?limit=30 |
| ^ Parameter ^ Values ^ Default ^ Description ^ | </code> |
| | ''style'' | string | ''chicago-note-bibliography'' | Citation style to use for formatted references. Should be the file name (without the .csl extension) of one of the default styles in the Zotero Style Repository (e.g., ''apa'' for https://www.zotero.org/styles/apa). Support for other styles is forthcoming.| | <code> |
| | Link: <https://api.zotero.org/users/12345/items?limit=30&start=30>; rel="next", |
| Note the difference between ''format=bib'' and ''content=bib''. ''format=bib'' returns a formatted bibliography as XHTML, sorted according to the rules of the selected style. ''content=bib'' (valid only for ''format=atom'', the default format mode) returns an individual formatted reference within the Atom ''<content>'' block for each item, with the Atom feed sorted according to the query parameters. ''format=bib'' processes the entire feed you are requesting without regard for any limit arguments, so it is generally a good idea to use it only with collections or tags. | <https://api.zotero.org/users/12345/items?limit=30&start=5040>; rel="last", |
| | <https://www.zotero.org/users/12345/items>; rel="alternate" |
| ==== Export Formats ==== | </code> |
| | |
| The following bibliographic data formats can be used as ''format'', ''include'', and ''content'' parameters: | |
| | |
| ^ Parameter ^ Description ^ | |
| | ''bibtex'' | BibTeX | | |
| | ''bookmarks'' | Netscape Bookmark File Format | | |
| | ''coins'' | COinS | | |
| | ''csljson'' | [[https://github.com/citation-style-language/schema/blob/master/csl-data.json|Citation Style Language data format]] | | |
| | ''mods'' | MODS | | |
| | ''refer'' | Refer/BibIX | | |
| | ''rdf_bibliontology'' | [[http://bibliontology.com/|Bibliographic Ontology]] RDF | | |
| | ''rdf_dc'' | Unqualified Dublin Core RDF | | |
| | ''rdf_zotero'' | Zotero RDF | | |
| | ''ris'' | RIS | | |
| | ''tei'' | Text Encoding Initiative (TEI) | | |
| | ''wikipedia'' | Wikipedia Citation Templates | | |
| |
| | (Newlines are inserted here for clarity.) |
| |
| ===== Caching ===== | ===== Caching ===== |
| ''Retry-After'' can also be included with ''503 Service Unavailable'' responses when the server is undergoing maintenance. | ''Retry-After'' can also be included with ''503 Service Unavailable'' responses when the server is undergoing maintenance. |
| |
| ===== Example Requests and Responses ===== | ===== Example GET Requests and Responses ===== |
| |
| TODO | TODO |
| |
| ===== Write Requests ===== | |
| |
| The API also supports [[write requests]] that allow the creation, modification, and deletion of data in Zotero libraries. | |
| |
| ===== HTTP Status Codes ===== | ===== HTTP Status Codes ===== |
| |
| ''429 Too Many Requests'' indicates that the client has been [[#rate_limiting|rate-limited]]. | ''429 Too Many Requests'' indicates that the client has been [[#rate_limiting|rate-limited]]. |
| | |
| | ===== Additional Documentation ===== |
| | |
| | * [[Write Requests]] |
| | * [[file_upload|File Uploads]] |
| | * [[Syncing]] |
| | * [[oauth|OAuth Authentication]] |
| | * [[changes_from_v2|Changes from API Version 2]] |
Upgrade Storage