/gawati-docs

Permalink
Branch: master
Find file Copy path
Fetching contributors…
Cannot retrieve contributors at this time
Raw Blame History
471 lines (371 sloc) 21.3 KB

Data Server APIs

Introduction

The Data Server has various APIs to access the Data from the Gawati System. The Data is accessible via REST APIs, which have been documented here. Full documents are served as Akoma Ntoso Documents.

These APIs allow accessing a list of documents or the document itself using different kinds of queries. Each API has 2 end points, an XML endpoint that produces outputs in XML (text/xml), and a JSON (application/json) end point that produces outputs in JSON.

Table of Contents

Listing of documents filtered by language

Returns a list of document abstracts (summaries) filtered by a specific language.

  • Method: GET
  • End-points:
  • XML endpoint - /gwd/search/languages/summary
  • JSON endpoint - /gwd/search/languages/summary/json
  • Parameters:
  • doclang - ISO639-2 Alpha 3 language code
  • count - the number of results to return
  • from - the paging point where to return results from.

Example:

The following makes a request for 1 english document in json format.

returns:

The following makes a request for 1 english document in XML format.

returns:

The outputs are exactly the same in terms of content, only the format differs.

Listing of documents filtered by year

Returns an abstracted list of documents, filtered by the year.

  • Method: GET
  • End-points:
  • XML endpoint - /gwd/search/years/summary
  • JSON endpoint - /gwd/search/years/summary/json
  • Parameters:
  • year - four digit year
  • count - the number of results to return
  • from - the paging point where to return results from.

Listing of documents filtered by keywords

Returns an abstracted list of documents, filtered by one or more keywords.

  • Method: GET
  • End-points:
  • XML endpoint - /gwd/search/keywords/summary
  • JSON endpoint - /gwd/search/keywords/summary/json
  • Parameters:
  • kw(1+) - keyword, this parameter can be specified multiple times
  • count - the number of results to return
  • from - the paging point where to return results from.

Note here that the kw parameter can be specified multiple times.

For example, the following returns 2 documents when the keyword Finance is specified:

returns abstracts for 2 documents:

When queried for 2 keywords, like below:

returns 3 documents (i.e. documents having either of the 2 keywords) :

Listing of documents filtered by countries

Returns an abstracted list of documents, filtered by one or more countries.

  • Method: GET
  • End-points:
  • XML endpoint - /gwd/search/countries/summary
  • JSON endpoint - /gwd/search/countries/summary/json
  • Parameters:
  • country(1+) - country, this parameter can be specified multiple times. Countries are specified as ISO ALPH-2 country codes.
  • count - the number of results to return
  • from - the paging point where to return results from.

Note here that the country parameter can be specified multiple times.

Listing of recent documents

Returns documents based on recency. Most recent appear first. Recency is established based on the updated date metadata of the document :

Return a complete document based on its IRI

Returns documents based on recency. Most recent appear first. Recency is established based on the updated date metadata of the document :

  • Method: GET
  • End-points:
  • XML endpoint - /gwd/doc
  • JSON endpoint - /gwd/doc/json
  • Parameters:

For example, to retreive the document with the IRI /akn/mr/act/1963-10-12/gn_no_150-1983/eng@/!main the following:

Note that to run this with curl we need to escape the ! character in the IRI as %21. returns, the XML document:

Advanced Document Filtering API

This API allows a more complex combination of filters, and conducting searches on the data server.

  • Method: GET
  • End-points:
  • XML endpoint - /gwd/search/filter
  • JSON endpoint - /gwd/search/filter/json
  • Parameters:
  • q - filter query, based on filter XQuery syntax (see below).
  • count - the number of results to return
  • from - the paging point where to return results from.

The query syntax for the q parameter runs pseudo XQuery:

For example, when q is set to the below, it returns documents only from the year 2016:

The below instead returns documents from both 2014 and 2016:

Note that the Portal front-end does not directly compose this query, there is an intermediate query translation api that lets the server make the request using a JSON based syntax. The below is the JSON query of the above :

These filters can be stacked, the below searches for documents from 2014 and 2016 which are from "Burkina Faso":

The Json query of the same would look like:

At this point the data server does not support JSON queries yet, but eventually the XQuery based API will be migrated to support only the JSON based API.

Another stacked filter supported is the language of the document:

And finally Keywords: