Fork me on GitHub

Entity Lookup Microservice API (ELMA)

Jakob Voß

2016-05-20 (version 0.0.4)

Table of Contents

1 Introduction

The Entity Lookup Microservice API (ELMA) is an HTTP API to look up and search for entities. An entity within the scope of this specification is any object identified by an URI and referred to by one primary label per language. In particular the API defines two request methods:

entity lookup
looking up an entity by its URI to get its primary labels and possibly other properties.
entity search
searching with a query string to get a list of possibly matching entities, each with label, descriptions, and entity URIs. This use case is also known as search suggestions, autocomplete, or type-ahead.

Use cases of ELMA microservices include semantic tagging, entity linking, and browsing in knowledge organization systems.

1.1 Status of this document

ELMA is currently being developed as part of project coli-conc and DINI AG KIM Normdaten as subset of JSKOS-API. The ELMA specification is hosted at http://gbv.github.io/elma/ and managed in the public GitHub repository https://github.com/gbv/elma. Feedback, for instance in form of GitHub issues, is appreciated!

This document can be shared freely under the terms of CC-BY-SA.

1.2 Conformance requirements

The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in RFC 2119.

2 Base URLs

An ELMA microservice MUST provide a base URL for entity lookup and SHOULD provide a base URL for entity search. Both base URLs MAY be identical. Base URLs MAY contain fixed query parameters except any of the reserved parameter names “uri”, “search”, “callback”, “language”, and “unique”.

3 Request and response format

3.1 Requests

An ELMA client SHOULD include the HTTP request header “Accept” with value “application/json” in every HTTP request. It should also include the “Accept-Language” request header for content negotiation as specified in RFC 7231.

An ELMA microservice MUST support HTTP GET requests and it SHOULD support HTTP OPTIONS requests and HTTP HEAD requests.

3.2 Responses

An ELMA microservice MUST include the following HTTP response headers in every HTTP response:

The response body of an ELMA microservice response to a HTTP GET request MUST be a syntacticaly valid JSON document (RFC 4627). This also applies to error responses. If an ELMA microservice supports JSONP, the JSON document can also be wrapped in a JavaScript function call. All string values in a JSON response SHOULD be normalized to Unicode Normal Form C.

An ELMA microservice SHOULD support Cross-Origin Resource Sharing (CORS), including preflight requests (HTTP request method OPTIONS and HTTP response headers “Allow”, “Access-Control-Allow-Methods”, and “Access-Control-Allow-Headers”).

An ELMA microservice at http://example.org/ is accessed via HTTP GET:

GET /?search=Paris
Host: example.org
Accept: application/json
Accept-Language: de, en;q=0.5, fr;q=0.2
Origin: http://example.com

The abbreviated response:

HTTP/1.1 200 OK
Access-Control-Allow-Origin: *
Content-Type: application/json

...JSON body...

An ELMA microservice MAY support JSONP as following: if a HTTP GET request URL contains the query parameter “callback” and if the value of this parameter only contain alphanumeric characters and underscores, then:

3.3 Error responses

Error responses with HTTP status code 4xx (client error) or 5xx (server error) MUST be returned with a JSON object response body. The following keys are RECOMMENDED:

code
the HTTP status error code
error
a custom error code. Allowed characters include a-z, 0-9 and underscore (_)
message
an optional human-readable error message, intended to be shown to an end user
error_description
an optional human-readable error description, intended for a developer, not an end user
error_uri
an optional URL of a human-readable web page with information about the error

The response header “Content-Language” MUST indicate the language of human-readable error message and description. The request header “Accept-Language” SHOULD be supported for content negotiation if error messages and descriptions are available in multiple languages.

An ELMA microservice implemented rate limiting and issued an error when the number of requests in a given span of time had been exhausted:

HTTP/1.1 429 Too Many Requests
Content-Type: application/json
Content-Language: en
{
  "code": 429,
  "error": "too_many_requests",
  "message": "Too many requests",
  "description": "Please slow down your request rate!",
  "error_uri": "http://example.org/api-policy" 
}

4 Request methods

4.1 Entity lookup

Entities can be looked up in ELMA microservice by an HTTP GET request at its lookup base URL and query parameter “uri”. The parameter value MUST be a syntactically correct IRI (RFC 3987). An error response with status code 422 SHOULD be returned if parameter “uri” is syntactically invalid or, if it is repeated.

The response to an entity lookup request MUST be an empty JSON array if no entity was found with the given URI or a JSON array containing one member otherwise. The response code MUST NOT be 404 if the entity was not found.

A found entity MUST be expressed as JSON object that conforms to the following restrictions:

Applications MAY include additional fields in uppercase letters or conforming to JSKOS data format.

The response format is aligned with JSKOS data format for Knowledge Organization Systems but neither ELMA services nor ELMA clients need to know about details of JSKOS.

The language tag “und” can be used for labels of unknown or unspecified language.

Request:

http://example.org/api?uri=http%3A%2F%2Fwww.wikidata.org%2Fentity%2FQ3431981

Response:

Content-Type: application/json
[
  {
    "uri": "http://www.wikidata.org/entity/Q5879",
    "prefLabel": {
      "de": "Johann Wolfgang von Goethe",
      "en": "Johann Wolfgang von Goethe",
      "ja": "ヨハン・ヴォルフガング・フォン・ゲーテ",
      "-": "..."
    }
  }
]

All URIs included in an entity search responses MUST result in a non-empty lookup response of the same ELMA microservice.

5 References

Normative references

Informative references

Changelog

0.0.3 (2016-05-04)

0.0.3 (2016-05-04)

0.0.2 (2016-05-02)