Skip to content

Commit 7ef9cac

Browse files
jacksonj04jacksonj04
authored
Merge pull request #176 from nationalarchives/FCL-283-move-some-API-docs-to-OpenAPI
[FCL-283] Improve OpenAPI specification
2 parents 6ebac1b + 49eee80 commit 7ef9cac

File tree

1 file changed

+100
-100
lines changed

1 file changed

+100
-100
lines changed

‎doc/openapi/public_api.yml

+100-100
Original file line numberDiff line numberDiff line change
@@ -1,148 +1,148 @@
1-
openapi: "3.0.3"
2-
1+
openapi: 3.1.0
32
info:
4-
title: Case Law Public API
5-
version: "0.1.3"
6-
description: National Archives Caselaw Public API
3+
title: "National Archives Find Case Law: Public API"
4+
version: 0.1.3
5+
description: |-
6+
Our API provides access to judgments and decisions held by Find Case Law that have been converted from Microsoft Word documents into XML. These have been automatically marked up according to the [international data standard, LegalDocML](https://groups.oasis-open.org/communities/tc-community-home2?CommunityKey=3425f20f-b704-4076-9fab-018dc7d3efbe), and validated by our legal editorial team. This data includes:
77
8-
servers:
9-
- url: https://{environment}.nationalarchives.gov.uk/
10-
variables:
11-
environment:
12-
default: caselaw
13-
enum:
14-
- caselaw # Production
15-
- staging.caselaw # Staging
8+
- Neutral Citation
9+
- Court / Chamber
10+
- Date
11+
- Case Name
12+
- Party Names
13+
- Judges' Names
1614
17-
tags:
18-
- name: Reading
19-
description: Operations for reading document content and metadata
15+
## Open Justice Licence
16+
17+
The National Archives, has worked in collaboration with The Ministry of Justice and the Judicial Executive Board to design a new licensing framework for the reuse of case law as data. The [Open Justice licence](https://caselaw.nationalarchives.gov.uk/open-justice-licence) is designed to protect the personal data within the records while supporting the principles of Open Justice.
18+
19+
The Open Justice licence allows you to copy, publish, distribute and transmit case law data. It permits you to use the data commercially, for example, by combining it with other information, or by including it in your own product or application. There are certain conditions that apply under this licence.
20+
21+
You do not need to apply to re-use Find Case Law records if your re-use complies with the terms and conditions of the Open Justice Licence.
22+
23+
**The Open Justice licence does not permit computational analysis.** If you intend to do any programmatic searching in bulk across the Find Case Law records to identify, extract or enrich contents within the records you will need to [apply to perform computational analysis](https://caselaw.nationalarchives.gov.uk/re-use-find-case-law-records/licence-application-process). There are no application charges.
24+
25+
## Give us your feedback
2026
27+
We are still actively developing Find Case Law based on user feedback. This includes improving the experience of how data re-users can access the data.
28+
29+
You can provide feedback by using our [feedback form](https://corexmsnp4n42lf2kht3.qualtrics.com/jfe/form/SV_0lyyYAzfv9bGcyW).
30+
termsOfService: "https://caselaw.nationalarchives.gov.uk/terms-of-use"
31+
contact:
32+
email: [email protected]
33+
url: "https://caselaw.nationalarchives.gov.uk/"
34+
name: Find Case Law
35+
license:
36+
name: Open Justice Licence
37+
url: "https://caselaw.nationalarchives.gov.uk/open-justice-licence"
38+
summary: "The Find Case Law API allows you to access court judgments and tribunal decisions held in the [Find Case Law service](https://caselaw.nationalarchives.gov.uk/), operated by the National Archives."
39+
servers:
40+
- url: "https://caselaw.nationalarchives.gov.uk"
41+
description: ""
2142
components:
2243
parameters:
23-
judgmentUri:
24-
name: judgmentUri
44+
documentUri:
45+
name: document_uri
2546
in: path
2647
required: true
2748
schema:
2849
type: string
2950
example: ewhc/tcc/2022/42
51+
description: The unique identifier for this document within Find Case Law.
3052
responses:
3153
judgmentFeed:
3254
description: An Atom feed of recently published judgments
3355
content:
34-
"application/atom+xml":
56+
application/atom+xml:
3557
schema:
3658
description: List in Atom
37-
# judgmentList:
38-
# description: An OData collection of judgment entities
39-
# content:
40-
# "application/xml":
41-
# schema:
42-
# description: An OData collection of judgment entities
4359
judgment:
44-
description: A single judgment document, in Akoma Ntoso XML
60+
description: "The contents of a single document, as [Akoma Ntoso XML](https://www.oasis-open.org/standard/akn-v1-0/)."
4561
content:
46-
"application/akn+xml":
62+
application/akn+xml:
4763
schema:
4864
description: Akoma Ntoso
49-
5065
paths:
51-
/{court}/{subdivision}/{year}/atom.xml:
66+
"/{court}/{subdivision}/{year}/atom.xml":
5267
get:
53-
summary: Get recently published or updated judgments
54-
description: >
55-
Less specific feeds can be gained by omitting the components
56-
e.g. /, /2022/, /ewhc/ and /ewhc/ch/ are all valid prefixes to atom.xml
57-
Note that a {court} is required if there is a {subdivision}
68+
summary: Get a list of recently published or updated documents
69+
description: |
70+
Less specific feeds can be gained by omitting the components e.g. `/`, `/2022/`, `/ewhc/` and `/ewhc/ch/` are all valid prefixes to `atom.xml`.
71+
72+
Note that a `{court}` is required if there is a `{subdivision}`.
5873
operationId: listJudgments
59-
tags:
60-
- Reading
6174
parameters:
62-
- name: court
63-
required: true
64-
in: path
65-
example: ewca
66-
schema:
67-
type: string
68-
- name: subdivision
69-
required: true
70-
in: path
71-
example: pat
72-
schema:
73-
type: string
74-
- name: year
75-
required: true
76-
in: path
77-
example: 2022
78-
schema:
79-
type: integer
8075
- name: order
8176
required: false
8277
in: query
8378
schema:
8479
type: string
8580
enum:
8681
- date
87-
- -date
82+
- "-date"
8883
- updated
89-
- -updated
84+
- "-updated"
9085
- transformation
91-
- -transformation
92-
default: -date
86+
- "-transformation"
87+
default: "-date"
88+
description: |
89+
Which of the dates within the document to use for ordering. Prepend a `-` to sort by newest first.
90+
91+
- `date`: The date the document was first published by the court
92+
- `updated`: The last date the document was updated in the Find Case Law system, including changes to its metadata
93+
- `transformation`: The date the body of the document was last modified, including changes to either the body text, XML markup, or both
9394
- name: page
9495
required: false
9596
in: query
9697
schema:
9798
type: integer
9899
default: 1
100+
minimum: 1
101+
description: "Where results are across multiple pages, the page of results to return."
99102
responses:
100103
"200":
101104
$ref: "#/components/responses/judgmentFeed"
102-
103-
# /judgments/advanced_search:
104-
# get:
105-
# summary: List published judgments
106-
# operationId: searchJudgments
107-
# tags:
108-
# - Reading
109-
# parameters:
110-
# - name: query
111-
# in: query
112-
# description: Free-text search term. Can include neutral citations
113-
# example: "[2021] EWCA Crim 1785"
114-
# - name: party
115-
# in: query
116-
# description: search in party name fields
117-
# example: John Doe
118-
# - name: judge
119-
# in: query
120-
# description: search for judge name
121-
# example: Lord Justice Smith
122-
# - name: court
123-
# in: query
124-
# description: search for judgments made by a specific court
125-
# example: ewhc/pat
126-
# - name: from
127-
# in: query
128-
# description: find judgments on or after the specified date
129-
# example: 1987-12-01
130-
# - name: to
131-
# in: query
132-
# description: find judgments on or before the specified date
133-
# example: 2022-04-14
134-
# responses:
135-
# '200':
136-
# $ref: "#/components/responses/judgmentList"
137-
138-
/{judgmentUri}/data.xml:
105+
tags:
106+
- Reading documents
107+
parameters:
108+
- name: court
109+
required: true
110+
in: path
111+
example: ewca
112+
schema:
113+
type: string
114+
description: The court code to return results for.
115+
- name: subdivision
116+
required: true
117+
in: path
118+
example: pat
119+
schema:
120+
type: string
121+
description: The court subdivision code to return results for.
122+
- name: year
123+
required: true
124+
in: path
125+
example: 2022
126+
schema:
127+
type: integer
128+
description: The year to return results for.
129+
"/{document_uri}/data.xml":
139130
get:
140-
summary: Read a published judgment or decision, given its URI
131+
summary: Get a single document
141132
operationId: getDocumentByUri
142-
tags:
143-
- Reading
144-
parameters:
145-
- $ref: "#/components/parameters/judgmentUri"
146133
responses:
147134
"200":
148135
$ref: "#/components/responses/judgment"
136+
tags:
137+
- Reading documents
138+
description: Retrieve the XML of a single document based on its identifier.
139+
parameters:
140+
- $ref: "#/components/parameters/documentUri"
141+
tags:
142+
- name: Reading documents
143+
description: |
144+
## Detecting content changes
145+
146+
Whenever a judgment gets changed it appears in the recently published list. This includes minor updates such as when we enrich the document with hyperlinks to other legal citations, as well as more significant changes such as revisions we have received from the courts.
147+
148+
Both the Atom feed and the judgment XML include a content hash so that you can check if the text of the document has changed.

0 commit comments

Comments
 (0)