Core

The Npolar::Api::Core is a HTTP request handler for manipulating documents in a collection. Each API endpoint runs its own core instance, allowing for customization of each collection's behavior.

The core's main task is to route requests to a Storage object that does the real work, including returning a Rack-style HTTP response triplet consisting of

• status code
• headers
• body (responding to #each)

Common statuses like 200 OK, 201 Created, 404 Not found are therefore not originating from the core. Likewise auth* failures (401/403) are returned from a Authorizer) or other security middleware.

The following are the most important error statuses returned by the core, with a JSON error document:

• 405 if request method is banned
• 406 if request format is unsupported
• 415 if POST or PUT document is in an unsupported format
• 422 if the POST or PUT body is invalid

Example: POSTing foo/bad

$ curl -XPOST -H "Content-Type: foo/bad" http://localhost:9393/metadata/dataset

HTTP/1.1 415 Unsupported Media Type
{"error":{"status":415,"reason":"Unsupported Media Type","explanation":"This API endpoint does not accept documents in 'bad' format, acceptable POST formats are: 'json'"}}

Configuration

Formats and accepts

Specify available outgoing formats (using :formats) and accepted incoming formats (using :accepts):

map "/metadata/dataset" do
  storage = Npolar::Storage::Couch.new(config_reader.call("metadata_storage.json"))
  run Npolar::Api::Core.new({:storage => storage,
    :formats=>["atom", "dif", "iso", "json", "solr", "xml"]},
    :accepts => ["dif", "json", "xml"]
  )
end

Methods

Use :methods to configure allowed HTTP verbs. Create a bullet-proof read-only API, by allowing only GET and HEAD.

run Npolar::Api::Core.new(nil, {:storage => storage, :methods => ["HEAD", "GET"])