REST API for Deichman's RDF-store

This is the API used in the Book Recommendations project by Oslo Public Library.

The reviews in the API are distributed under a Creative Commons license: Navngivelse-DelPåSammeVilkår CC BY-SA 3.0 NO

Available routes and HTTP methods

The API will be expanded as we see fit. Currently only the /reviews and /works endpoints are implemented.

The API is open for anyone to use, but a key is required in order to write to the API (i.e perform POST/PUT/DELETE requests). Please get in touch if your library wants to publish to our RDF-store.

The Reviews Endpoint

Architecture

Endpoint

https://anbefalinger.deichman.no/api
(fallback: https://marc2rdf.deichman.no/api)

The return format is JSON. All responses from /api/reviews and /api/works now responds to the format:

"works" : [
  { "uri" : "https://example.com/workid",
    "originalTitle" : "Title of work",
    "prefTitle": "Norwegian title of work", 
    "authors": [
      {
      "uri": "https://example.com/authorid",
      "name": Author's name",
      }
    ],
    "editions": [
      {
      "uri": "https://example.com/editionid",
      "lang": Edition's language",
      "title": Edition's title",
      "isbn": Edition's isbn",
      "cover_url": Edition coverimage",
      }
    ],
      ...
    "reviews" : [ 
      {
      "uri": "https://example.com/review_id",
      "title": "A Review Title",
      "reviewer": {
        "uri": "https://example.com/reviewer_id",
        "name": "Reviewer's name"
        },
      "source": {
        "name": "Deichmanske Bibliotek", 
        "uri": "https://data.deichman.no/source/deichmanske_bibliotek"
        },
      "audience": [
        "Voksen"
        ],
      "teaser": "Short teaser to review",
      "text": "Full Text of review...",
      }
    ]
  }
]
         

GET /reviews

Fetches one or more reviews

Allowed parameters: reviewer, work, author, isbn, author_name, title, source

Filtering parameters: order_by, order, limit, offset, published, cluster

• Other parameters will be ignored if uri, reviewer or work is present.
• The uri must refer to a bookreview. uri can also be an Array of uris
• reviewer, work, author, reviewer, and source must be a uri
• offset and limit must be integers.
• order_by allows values author_name, title, reviewer, issued, modified, created
• order must be desc or asc.

Examples

http GET https://anbefalinger.deichman.no/api/reviews uri="https://data.deichman.no/bookreviews/deich3456"
http GET https://anbefalinger.deichman.no/api/reviews uri:='["https://data.deichman.no/bookreviews/deich3456",
                                                    "https://data.deichman.no/bookreviews/deich3457"]'
http GET https://anbefalinger.deichman.no/api/reviews reviewer="https://data.deichman.no/reviewer/id_0"
http GET https://anbefalinger.deichman.no/api/reviews work="https://data.deichman.no/work/x18370200_snoemannen"
http GET https://anbefalinger.deichman.no/api/reviews limit=20 offset=20 order_by=author_name order=desc

GET /works

Fetches one or more works, optionally with reviews

Allowed parameters: uri, isbn, title, author, author_name

• Other parameters will be ignored if urior isbn is present.
• The uri must refer to a work id.
• offset and limit must be integers.
• order_by allows values author_name, title, issued, modified, created
• order must be desc or asc.

Examples

http GET https://anbefalinger.deichman.no/api/works uri="https://data.deichman.no/work/x18370200_snoemannen" reviews=true
http GET https://anbefalinger.deichman.no/api/works uri:='["https://data.deichman.no/resource/work/x123456",
                                                    "https://data.deichman.no/resource/work/x123456"]'
http GET https://anbefalinger.deichman.no/api/works title="Test Title"
http GET https://anbefalinger.deichman.no/api/works author="Jo Nesbø" reviews=true limit=10 order_by=author_name order=desc

POST /reviews

Creates a new review

Parameters

• Required: api_key, isbn, title, teaser, text

• Optional: reviewer, reviewer_name, audience

  allowed audience values are voksen, adult, ungdom, youth, children or barn can be multiple separated by either comma, slash or pipe (,/|) reviewer must be valid e-mail. If e-mail is new, a new user and useraccount will be created. If no reviewer, anonymous will be used. Reviewer's name will be set to e-mail if reviewer_name param is not used

Example

http POST https://anbefalinger.deichman.no/api/reviews api_key="dummyapikey" isbn=9788243006218 title="Title of review"
    teaser="A brief text for teaser, infoscreens, etc." text="The entire text of review. Lorem ipsum and the glory of utf-8"
    reviewer="test@person.com" audience="children"

PUT /reviews (or POST /reviews/update for agents not supporting PUT/DELETE)

Updates existing review

Parameters

• Required: api_key, uri

• Optional: title|teaser|text|reviewer|audience

  uri must refer to the URI of an already published review

DELETE /reviews (or POST /reviews/delete for agents not supporting PUT/DELETE)

Deletes a review

Parameters

• Required: api_key, uri

Returns

JSON hash result string