Organisations API
Where the Organisations API lives
There is a read-only Organisations API that returns either a JSON list of organisations, or a single organisation by its slug.
- JSON list of organisations: https://www.gov.uk/api/organisations
- Example of an organisation by slug: https://www.gov.uk/api/organisations/government-digital-service
The /api/organisations route is published as a special prefix route by Collections Publisher. The routes therefore don’t exist in Publishing API or Content Store.
Requests to these routes are handled by Collections (frontend). The OrganisationsApiController file uses Search API to fetch the organisations before returning the API response with the help of an OrganisationsApiPresenter.
The Organisations API response is very similar to what one would get from querying Search API directly: https://www.gov.uk/api/search.json?filter_format=organisation.
Not to be confused with the Organisations index and Content API
As an aside, Collections has two competing methods for retrieving organisations. As stated above, Search API powers the Organisations API response, but a different mechanism is used to power the user-facing organisations pages:
- List of organisations: https://www.gov.uk/government/organisations
- Example of an organisation homepage: https://www.gov.uk/government/organisations/government-digital-service
These user-facing pages are also handled by Collections, but they use Content Store to retrieve the organisation info.
- Organisations index page content item: https://www.gov.uk/api/content/government/organisations
- Example of an organisation content item: https://www.gov.uk/api/content/government/organisations/government-digital-service
Consuming the Organisations API
The API is surfaced through GDS API Adapters, returning either a list of organisations or a specific organisation by its slug. The base URL of the requests is the website root www.gov.uk, so we can easily query the API in the browser as described earlier. To be clear, this is hitting Collections under the hood.
Several apps rely on the Organisations API (via GDS API Adapters). For example, Signon fetches the organisations list to ensure its own internal list of orgs is in sync.
Populating the Organisations API
Organisations are created, edited and deleted in Whitehall, modelled as an Organisation that pulls in several key modules.
The PublishesToPublishingApi module is responsible for giving each organisation a random content ID, and for publishing to Publishing API whenever a model is updated. The model defines callbacks for republishing the organisations index page (content item) whenever an org is updated or deleted. These Publishing API interactions power the user-facing organisation pages described earlier.
The Searchable module defines the behaviour for indexing the organisation after save, and unindexing it after destroy. This Search API interaction is ultimately what powers the Organisations API. As an aside, Whitehall really shouldn’t be updating Search API directly - work is currently underway to attempt to remedy that.
Also worth noting that the OrganisationSearchIndexConcern module ensures that the organisation’s corporate information pages (such as ‘About’ - example) are added to or removed from GOV.UK’s search index.