# Tausi API The Tausi API is a read-only, REST, JSON-based API that allows external services to fetch structured and formatted decisions from Tausi. The API is implemented using [Django Rest Framework](https://www.django-rest-framework.org/) which takes care of the bulk of the API plumbing. Only published decisions are available through the API. Decisions that are still being processed and reviewed are not available. **NOTE:** Full API documentation will follow, once the API has been implemented. ## Versioning The API is versioned using a version number in the URL. Backwards incompatible changes to the API require a new API version. ## Location The API is available at the path `/api/v1/`. ## Data formats The API is a REST API that primarily uses JSON as a data format. Some requests can also return XML, HTML or PDF data. ## Authentication Calls to the API must be authenticated using your API token. To get a token, 1. Sign into your Tausi account 2. Get your API token from your profile page Include your API token in your API calls by including an Authorization header: Authorization: Token YOUR_AUTH_TOKEN API access also requires a dedicated permission that gives full access to all the listable content types available via the API. ## Pagination API calls that return lists will be paginated and return a limited number of items per page. The response includes information on the total number of items and the URLs to use to fetch the next and previous pages of items. Here's an example of the first page of a paginated response with 250 total items and two pages: { "count": 250, "next": "https://example.com/api/v1/decisions/.json?page=2", "previous": null, "results": [ "..." ] } In this case, fetching the next URL will return the second (and final) page. ## FRBR URIs Decisions are uniquely identified by an [FRBR URI](http://docs.oasis-open.org/legaldocml/akn-nc/v1.0/akn-nc-v1.0.html). This is a special URI used by the Akoma Ntoso data standard that uniquely identifies a decision. The FRBR URI corresponds directly to the [Medium-Neutral Citation (MNC)](mnc.md) for the decision. For example, the decision with MNC `[2018] KEHC 500 (KLR)` has the FRBR URI `/akn/ke/judgment/kehc/2018/500`. ## Listing decisions `/api/v1/decisions` will be used to return the paginated listing of decisions. ### List decisions GET /api/v1/decisions/.json This will list all decisions (judgments) for Kenya. ### List decisions for a court and a year GET /api/v1/decisions/?court=:court GET /api/v1/decisions/?court=:court&year=:year This will list all decisions for a court identified by the court code `:court` and the `:year`. ### Filtering lists Various filters can be applied to listings, using the formats supported by Django Rest Framework. This is achieved using the [DjangoFilterBackend](https://www.django-rest-framework.org/api-guide/filtering/#djangofilterbackend) extension. For instance, to get all the cases delivered in 2020 in the High Court at Nairobi, the request endpoint would be: GET /api/v1/decisions/?year=2020&court=HCNRB The various filter parameters include: * Court (unique code) * Court division * Court class * County * Delivery year * Filing year * Flags * Case type * Anonymisation status * Area of law ## Get decision details The primary URL for a decision would be `/decisions/` GET /api/v1/decisions/akn/ke/judgment/:court/:year/:number.json Fetches the JSON details of a decision which includes accompanying metadata such as: * court data * flags * judges information * advocates information ### Response format The JSON response for the details of a single decision will include details of the nested fields such as parties, judges, courts and counties. [Django Rest Framework](https://www.django-rest-framework.org/) offers support for the serialization of nested objects as described [here in the documentation.](https://www.django-rest-framework.org/api-guide/serializers/#dealing-with-nested-objects) Here is an example of a response containing a subset of a decision's details: { "short_mnc": "[2020] KEHCBS 23 (KLR)", "full_mnc": "Honey Bee Limited v B & another (Civil Suit 444 of 2019) [2020] KEHCBS 23 (KLR) (Civ) (10 November 2020) (Ruling)", "case_number_string": "Civil Suit 444 of 2019", "case_number_numeric": 444, "filing_year": "2020, "action": { "name": "Ruling", "decsription": null }, "casetype": { "name": "Civil Suit", "description": null }, "filing_county": { "name": "Nairobi", "code": 47 }, "court": { "name": "High Court at Busia", "code": "HCBS", "mnc_code": "KEHCBS", "county": { "name": "Busia", "code": 40 }, "court_class": { "name": "High Court" } }, "judges": [ { "name": "Robert Kipkoech Limo", "short_name": "RK Limo", "title": "Judge" }, { "name": "Stella Ngali Mutuku", "short_name": "SN Mutuku", "title": "Judge" } ], "advocates: [ { "name": "Advocate Z", "for_party": "Honey Bee Limited" }, { "name": "Advocate Y", "for_party": "Party B" } ], "parties": [ { "name": "Honey Bee Limited", "name_for_citation": "Honey Bee Limited", "party_group": 1 }, { "name": "Party B", "name_for_citation": "B", "party_group": 2 }, { "name": "Party C", "name_for_citation": "C", "party_group": 2 }, ], "flags": [ { "label": "Law reform", "color": null, "description": "Law reform issue" }, { "label": "Flag 2", "color": null, "description": null } ], } ## Get decision content GET /api/v1/decisions/akn/ke/judgment/:court/:year/:number.xml GET /api/v1/decisions/akn/ke/judgment/:court/:year/:number.html GET /api/v1/decisions/akn/ke/judgment/:court/:year/:number.pdf Fetches the content (body) of a decision in various formats. ## Other listable content types Extra listable content types are made available to enhance the filtering of decisions. The following is a list of the other listable content types and their endpoints: ### Courts GET /api/v1/courts Fetches a list of courts. GET /api/v1/courts/:court_code Fetches the details of a single court matching the provided `:court_code`. ### Court divisions GET /api/v1/courtdivisions Fetches a list of available court divisions. ### Court classes GET /api/v1/courtclasses Fetches a list of available court classes. ### Flags GET /api/v1/flags Fetches a list of available flags. ### Judges GET /api/v1/judges This endpoint returns a list of judges. GET /api/v1/judges/:id Fetches the details of a single court matching the provided judge `:id`. ### Case Types GET /api/v1/casetypes This will list available case types. ### Case Actions GET /api/v1/caseactions Fetches a list of case actions. ### Areas of Law GET /api/v1/areasoflaw Fetches a list of areas of law. ### Counties GET /api/v1/counties Fetches a list of counties. ## Search Full-text, faceted search across published decisions is achieved using ElasticSearch. This requires all published decisions to be indexed on the Elastic Search host. This adds functionality such as: * Find-as-you-type * Modern language support such synonyms and stemming * Spelling corrections support The search API will be available at: GET /api/v1/search Parameters: * `q`: free-text search string * `filters`: filters to apply to search results, as per listing filters TODO: Search API specification and output to be finalised