This document is a DRAFT
This specification describes the API through which MOJ's court and tribunal finder sends court data to GDS in order to produce individual court pages on www.gov.uk. The administration and search functionality of courts are out of the scope of this document, as well as operational aspects such as message queuing, retry-on-error, logging and monitoring.
Throughout this document, the term sender is used to refer to the system pushing the court data through the API, while the term receiver denotes the system receiving the data and publishing a representation of it online. The terms 'must', 'may' and 'should' follow the definitions in RFC 2119
A court is described by a collection of properties encoded as text. For instance, the court's name, or its address, as well as some binary data representing a court's picture.
Those properties are organised in a hierarchy. For instance, a court can have multiple addresses, each of which having one town name. JSON is used to serialise the textual data passed through the API, while some image format TBD is used for encoding a court's picture.
A court is identified by a UUID, which the sender generates for new courts and uses to modify or delete existing courts. The format of court UUIDs must match the following regexp (in Ruby syntax):
UUID_PATTERN = %r{
\A
[a-f\d]{8}
-
[a-f\d]{4}
-
[1-5] # Version: http://tools.ietf.org/html/rfc4122#section-4.1.3
[a-f\d]{3}
-
[89ab] # Variant: http://tools.ietf.org/html/rfc4122#section-4.1.1
[a-f\d]{3}
-
[a-f\d]{12}
\z
}x
From the content-store on 23-12-2014
A court's UUID must never change in the lifetime of a court. A UUID must also never be reused after a court has been deleted.
Authentication is done with a token, which needs to be supplied in the Authorization HTTP header, like this:
Authorization: Bearer your_token
You also need to supply an accept header and a Content-Type header:
Accept: application/json
Content-Type: application/json
Please note that:
- Tokens are environment specific, so preview and production will have different tokens.
- The data on preview is overwritten every night with data from production.
PUT https://{base}/courts/{uuid}
...to change or create a court.
base is predefined by the receiver. In the preview environment, base is https://courts-api.preview.alphagov.co.uk. The body of the request contains the description of the court, which must conform to the court JSON schema described below. Upon receiving the data, the receiver generates or updates a court page.
On success, the receiver responds with a 201 Created status code if a new court is created (as a result of the sender passing a new UUID passed in the request URL), or a 200 OK if the call updates an existing court.
In both cases, the body of the response must be a JSON string containing the full URL of the court's public page:
{"public_url":"https://www.gov.uk/{prefix}/{slug}"}
The prefix is generated by the receiver and the slug must be the same as that passed in the court JSON object.
The URL returned is not necessarily the URL that is passed in the PUT call.
If a court's slug changes, the receiver must create HTTP redirects of the public URLs to avoid broken links.
Errors are returned through standard HTTP response codes: 4XX on sender errors (eg, 422 if the court data passed is invalid) and 5XX on server errors. Response bodies should return helpful information about the error.
In rare circumstances, typically following the mistaken creation of a court, a court's page needs to be removed from public view. The sender sends:
DELETE https://{base}/courts/{uuid}
The receiver must return one of the standard HTTP response codes, as above, with optional informative response body. The receiver must alter the corresponding court page so that it is no longer visible to the public. The UUID of a deleted court must never be reused.
The sender must not use this API call to indicate that a court or a tribunal has been closed. In that case, a court modification request is sent, with "closed":true in the court data passed.
GET https://{base}/courts/{uuid}
retrieve information on a single court. Details TBD.
GET https://{base}/courts
Return a list of all the courts. Details TBD.
TBD.
All court data passed through the API by the sender or the receiver (in the body of API requests) must be encoded in UTF-8 and must validate against the JSON-schema below. Moreover, the text fields in the payload must be plain text and must not contain any formatting elements: markup (like HTML or Markdown), escape sequences (eg & or '\n').
{
"name": "Accrington Magistrates' Court",
"slug": "accrington-magistrates-court",
"updated_at": "2014-03-18T12:33:12.176Z",
"update_type": "major",
"locale": "en",
"closed": false,
"alert": "There is an intermittent fault with our telephone number and it is sometimes unavailable.",
"lat": 53.7491281247251,
"lon": -2.359323760375266,
"court_number": "1725",
"DX": "730458 Blackburn 10",
"areas_of_law": [
"Crime", "Adoption"
],
"facilities": [
{"type": "guide_dogs", "description": "Guide Dogs are welcome at this court."},
{"type": "interview_room", "description": "Two interview rooms are available at this court."}
],
"parking": [
{"type":"onsite", "description":"On site parking is not available at this venue."},
{"type":"offsite", "description": "Paid off site parking is available within 500m of this venue."},
{"type":"blue_badge", "description": "Blue badge parking is not available at this venue."}
],
"opening_times": [
{"name":"Court building open", "description": "Monday to Friday 9:15am to close of business"}
],
"addresses": [
{
"type": "visiting",
"town": "Accrington",
"county": "Lancashire",
"postcode": "BB5 2BH",
"lines": ["East Lancashire Magistrates' Court","The Law Courts","Manchester Road"]
},
{
"type": "postal",
"town": "Blackburn",
"county": "Lancashire",
"postcode": "BB2 1AA",
"lines": ["Accrington Magistrates' Court", "The Court House", "Northgate"]
}
],
"contacts": [
{
"name": "Fax",
"number": "0870 739 4254"
},
{
"name": "Enquiries",
"number": "01254 687500"
},
{
"name": "Fine queries",
"number": "01282 610000"
},
{
"name": "Witness Service",
"number": "01254 265 305"
}
],
"emails": [
{
"name": "Enquiries",
"address": "ln-blackburnmcenq@hmcts.gsi.gov.uk"
}
]
}
TODO: Write court JSON schema
Court slugs are the court-specific part of courts public URIs, for instance https://www.gov.uk/court/alderton-magistrates-court. Court slugs are generated by the sender, and passed to the receiver in the body of a court creation/update call.
The sender may change a court's slug indpendent of its name, but a slug must always follow the URL standards for GOV.UK. It is the sender's responsibility to ensure that no two courts have the same slug. The receiver must reject a court with the same slug as an existing one with a different UUID.