Skip to content

Pubs API

Jump to bottom Edit New page
pjcraig edited this page May 16, 2013 · 15 revisions

Indiana University Cognitive Science Pubs API

About

The IU Cogsci Pubs API is a RESTful API that allows for the programmatic retrieval, parsing and insertion of citation and collection information from the Cognitive Science citations database. Unless otherwise noted, all API output is in JSON.

Resources

All get and post requests should be directed to one of the following resources under pubs.cogs.indiana.edu

POST /citation

Takes a JSON string of a parsed citation to be inserted

Returns the ID of either the newly inserted citation OR the pre-existing citation ID if the citation is already in the database.

POST /citation/parse

Takes a raw citation string

Returns a JSON string containing the parsed citation.

POST /citation/match

Takes a raw citation string

Returns a JSON of potentially matching citations

GET /citation?IDs={citation IDs}

Takes an arbitrary number of existing citation IDs delimited by commas.

Returns the JSON of each citation ID passed to it.

GET /collection?IDs={collection IDs}

Takes an arbitrary number of existing collection IDs delimited by commas

Returns a JSON array of collection data, including the citation IDs contained in each collection

POST /collection?collectionNames={collection names}&submitters={submitter names}&owners={owners}

Takes an arbitrary number of the name of a new collection to be added, the submitter's username (by default, "API User") and the owner of the collection. These are delimited by newline characters (\n)

Returns the string "exists" and the collection ID if the submitted collection already exists. If not, returns and array with 1 followed by the new collection ID.

PUT /collection?collectionID={collection ID}&citationIDs{citation IDs}&submitter={submitter}&owner={owner of collection}

Adds an arbitrary number of citations to a collection.

Takes the collection ID of the collection, the citation IDs, delimited by commas, as well as the submitter's username (by default, "API User"), and the owner of the collection.

Returns a JSON of the collection added to, citations added to the collection as well as any duplicates in the collection.

Data units

There are two basic units in Pubs: citations and collections.

Citations

Citations in the database are a collection of information about the cited material as well as information about when it was inserted, modified, who owns it and who actually inserted it.

Fields include:

  • citation_id - the ID of the citation, an identifier unique to a citation
  • pubtype - the type of the publication: article, book, edited book, conference, in book, in collection, in proceedings, manual, master's thesis, phd thesis, proceedings, tech report, unpublished, miscellaneous, translated book, and web published
  • abstract - a text field for storing a description/abstract of the citation
  • keywords - a field for storing keywords related to an article. These add to the robustness of our search
  • doi - digital object identifier number of the citation, if any
  • URL - the internet address a citation was retrieved from
  • annote - a field for annotations for a given citation
  • authorxln or authorxfn - where x is a number between 0 and 5 inclusive. These are the authors' last names (ln) and first names (fn) Currently citations are hard coded for a maximum of six authors, but this will change in the future
  • booktitle - title of the book a given citation was included in, if any
  • chapter - the chapter the citation appears in
  • crossref - for any cross references
  • edition - the edition of the citation
  • editor - editor of the citation
  • translator - translator, if from a translated book
  • howpublished - a field for a description of how a given citation was published. Examples include "Court files", "web" and "conference talk"
  • institution - institution the citation is from
  • journal - the journal a given citation was published in
  • bibtex_key - used to cite or cross-reference bibtex entries
  • month - the month a given citation was published in
  • note - a field for notes
  • number - number of a journal that a given citation was published in
  • organization - organization responsible for publishing a citation
  • pages - the page numbers a citation was printed on
  • publisher - the publisher of a citation
  • location - the location the citation was published at
  • school - the school a citation was published by/at
  • title - the title of a citation
  • volume - the volume a citation was published in
  • year - the year a citation was published in
  • raw - the raw string fed into the parser to generate the citation now in the database. Citations which were manually entered do not have raws
  • verified - whether or not a given citation was verified.
  • format - format a citation was entered in, i.e. APA/MLA
  • filename - filename of any uploaded citation
  • submitter - the username of the submitter of the citation to the database. Citations submitted by the API are marked as "apiuser"
  • owner - the owner of the citation. The citation will show up in this user's citations when using the Pubs web interface
  • entryTime - Unix timestamp of when a citation was entered into the database
  • last_modified - Unix timestamp of when a citation was last edited
  • date_retrieved - for web publications, the date a publication was retrieved

Collections

Collections are groupings of these citations. Uses for collections are grouping citations for use in papers, books or for organizing them to another end, such as building a collection of citations with a given author or publisher.

Fields include

  • collection_id - unique identifier of a collection in the database
  • collection_name - the name of the collection
  • submitter - the user who created the collection
  • owner - the user who owns the collection- the collection is accessible to this user within the Pubs web interface
Add a custom footer
Add a custom sidebar

Clone this wiki locally