Skip to content
This repository has been archived by the owner on Nov 21, 2018. It is now read-only.

API documentation

Jump to bottom
adam malantonio edited this page Feb 13, 2018 · 8 revisions

this is just a work-in-progress sketching of the API + the routes needed

intro

request method

Only GET requests are available.

pagination

Every route supports pagination. To utilize this, use the page and per_page keys in your query string like so:

/loans?page=2&per_page=50

Note: the default value for per_page is 40. If you're finding that this isn't enough, feel free to submit an issue in the Rails app repository and I'd be happy to make the change

search

Most routes (where specified) support very basic search capabilities. These are using a WHERE/LIKE query against the title, label, or name fields. To use this, simply add q=<search term> like so:

/works?q=intrepid

response format

As of now, there are only two types of responses you can get back from the server: those with single objects and those with multiple. The single object responses will always be a JSON object containing the requested thing. Multiple-object responses will always look like:

{
  "data": [
    {
      "id": 4,
      "label": "Belles Letters: Dramatical Works"
    },
    {
      "id": 5,
      "label": "Belles Letters: Essays"
    },
    {
      "id": 6,
      "label": "Belles Letters: General"
    }
  ],
  "meta": {
    "total": 51,
    "page": 2,
    "per_page": 3,
    "total_pages": 17
  }
}

response.data will be an array containing the works and response.meta will be an object with some data to help with pagination:

key description
total total number of works
page what page of data you're on
per_page how many works per page
total_pages how many pages in total are there (calculted by ceil(total / per_page))

errors

These have a ways to go to get better. As of now, only 404s for single-work requests receive what I'm hoping to be the standard layout of error responses:

{
  "error": "Couldn't find Subject with 'id'=500",
  "status": 404
}

I would check the status code of the response before relying on the JSON response for the time being.

a note on ids

In the early stages we'll be using ids generated by Rails when the database is seeded, which means that they'll be Numbers. The goal is to eventually move ID generation to the work-inputting stage (via spreadsheet), where they'll be set as unique strings (something like loan-ledger-1-000001).

index (/)

returns counts for each type of object in the database. this is mostly to have something here, but could be useful for debugging?

index object response

{
  "status": "🎃",
  "counts": {
    "authors": 790,
    "works": 2022,
    "ledgers": 5,
    "loans": 25325,
    "patrons": 531,
    "subjects": 51
  }
}

works

Work objects represent individual materials within the Easton Library Company.

routes

  • /works
  • /works/:id
  • /works/:id/loans
    • this will conduct a search of Loans whose borrowing item shares a work of :id (see Loan objects).
  • /works/search?q=<query>

work object

{
  "id": 1234,
  "title": "Whims and oddities",
  "format": "Duodecimo",
  "number": 1157,
  "authors": [
    {
      "id": 114,
      "name": "Hood, Thomas"
    }
  ],
  "subjects": [
    {
      "id": 28,
      "label": "Miscellaneous Works"
    }
  ]
}
key type description
id Number the unique identifer for the work
title String title of the work
format String physical format of the book (used to determine the location)
number String catalog number within the location (ex: "Duodecimo 1157")
authors Array an array of Author objects
subjects Array an array of Subject objects

authors

Author objects represent the people who wrote the works in the collection. Authors are almost identical to Patron objects and in the future may contain a "type": "Author" field.

routes

  • /authors
  • /authors/:id
  • /authors/:id/works
    • this will conduct a search of Works whose Author is :id (see Work objects)
  • /authors/search?q=<query>

author object

{
  "id": 15,
  "name": "Montagu, Elizabeth",
  "types": [
    "Author"
  ]
}
key type description
id Number the unique identifer for the author
name String name of the author (last name first)
type Array this is hard-coded to return ["Author"] for now

subjects

Subject objects represent categories of works. An work can have multiple subjects.

routes

  • /subjects
  • /subjects/:id
  • /subjects/:id/works
    • this will conduct a search of Works containing a Subject of :id (see Work objects)
  • /subjects/search?q=<query (label)>

subject object

{
  "id": 15,
  "label": "Encyclopedias"
}
key type description
id Number the unique identifer for the subject
label String label of the subject

patrons

Patron objects represent the people that circulated materials from the library. The following terminology was created to differentiate the two types of patrons:

  • A Shareholder is a member of the Easton Library Company. Every ledger has a page for this person.
  • A Representative is a person borrowing materials with the permisssion of a Shareholder.

With regards to loans, the Representative is the person borrowing the works and the Shareholder is the one ultimately responsible for them. I believe there is a one-to-many Shareholder/Representative relationship, but it's conceivable that a Representative could be represented by multiple Shareholders.

Note: when a Shareholder borrows an work, they are listed as both the Representative and Shareholder

routes

  • /patrons
  • /patrons/:id
  • /patrons/:id/loans
    • this will conduct a search of Loans whose Shareholder or Representative equals :id (see Loan objects)
  • /patrons/search?q=<query (name)>

patron object

{
  "id": 95,
  "name": "Wagener, David D.",
  "types": [
    "Shareholder",
    "Representative"
  ]
}
key type description
id Number the unique identifer for the patron
name String name of the patron (last name first)
types Array array of labels for the person types

loans

Loan objects represent a line within a ledger, which itself represents the circulation of an work to a Patron.

routes

  • /loans
  • /loans/:id

loan object

{
  "id": 21453,
  "label": "Eigs, Joel Jones borrowed \"Orations [Vol. 1] (Octavo 89)\" on Saturday, August 30, 1828",
  "work": {
    "id": 773,
    "title": "Orations [Vol. 1] (Octavo 89)",
    "author": null,
    "subjects": [
      {
        "id": 8,
        "label": "Belles Letters: Oratorical Works"
      }
    ],
  },
  "volumes": [],
  "issues": [],
  "years": [],
  "checkout_date": "1828-08-30T00:00:00.000Z",
  "return_date": "1828-09-13T00:00:00.000Z",
  "representative": {
    "id": 516,
    "name": "Eigs, Joel Jones"
  },
  "shareholder": {
    "id": 83,
    "name": "Shouse, William"
  },
  "ledger": {
    "id": 3,
    "filename": "ELCv3_C_205",
    "url": "https://elc.lafayette.edu/collections/eastonlibrary/ELCv3_C_205"
  }
}
key type description
id Number the unique identifer for the loan
label String description of the loan (who borrowed what when)
work Object see Work object
volumes Array The volumes of work that were borrowed
issues Array The issues of work that were borrowed
years Array The years of work that were borrowed
checkout_date String Date
return_date String Date
representative Object the borrowing patron (see Patron object)
shareholder Object the shareholder for the loan (see Patron object)
ledger Object the containing Ledger (see note below)

Note: the ledger object represents the ledger that contains the loan record. While a route for /ledgers(/:id(/loans)) exists, it's a little unhelpful at the moment: the single object contains only an id Number, and per-ledger browsing (via /ledgers/:id/loans) is not required for the initial product.

key type description
id Number the unique identifier for the ledger
filename String the file name of the ledger page associated with the loan
url String a url to the image viewer displaying the ledger
Clone this wiki locally