The REST API as a data interface #

This page is for developers and administrators who want machines to read dataset descriptions and file links directly. Exponential serves a REST content API from one extension, ezprestapi, at /api/ezp/v1/... and /api/ezp/v2/.... Everything below is from REST API v1 and v2 and Personal API keys.

Contents #

1. What it returns
2. Authentication by default
3. Opening it to anonymous readers
4. Calls a data client makes
5. What it is not
6. Before you announce it

What it returns #

Reads answer at v1 and v2; writes only at v2. Answers are JSON.

A catalog folder read with list gives the datasets; each dataset read with fields gives its metadata; each distribution's file field gives the file information.

Authentication by default #

rest.ini [Authentication] RequireAuthentication=enabled is the default: every content route needs a user, either with an OAuth2 token (registered at Setup > oAuth admin) or with a personal API key sent as Authorization: Bearer expk_.... Every read checks the user's content/read policy, so a client never sees more than that user may.

Opening it to anonymous readers #

RequireAuthentication=disabled lets every request run as DefaultUserID, or the anonymous user when that is empty; the permission checks still apply, so anonymous clients see exactly what anonymous visitors of the site see. Before you change it:

1. Make sure the Anonymous role reads only public sections (Visitor permissions).
2. Decide whether write routes must stay closed: they still check content/create, content/edit and content/remove, which Anonymous must not have.
3. Plan for load: a public API can be called in bulk. Put rate limits in front of it (web server or request shield, Security hardening).
4. Set RequireHTTPS in rest.ini if your deployment allows it.
5. Clear the INI cache after the change (php bin/php/ezcache.php --clear-tag=ini).

This is a security decision; record who approved it.

Calls a data client makes #

# the datasets of the catalog folder, 50 at a time
curl -s "https://www.example.gov/api/ezp/v2/content/node/<catalog node id>/list/offset/0/limit/50"

# the metadata of one dataset
curl -s "https://www.example.gov/api/ezp/v2/content/node/<dataset node id>/fields"

# only its license
curl -s "https://www.example.gov/api/ezp/v2/content/node/<dataset node id>/field/license"

Add -H "Authorization: Bearer expk_..." while authentication is required.

What it is not #

• Not a query interface over the data inside your files. The API serves content objects and their fields; a CSV file is a file field, not rows you can filter.
• Not DCAT. The JSON follows the API's own structure, not a catalog vocabulary.
• The Atom route listAtom answers 500 (known issue, section 8 of the guide); use Setup > RSS for feeds.

Before you announce it #

• To do: Decide authenticated or anonymous, and document how clients get a key.
• To do: Publish a short page with the base address, the calls above and the license of the data.
• To do: Watch the request logs and the audit trail after launch (Request logs, Audit trail).

Related pages #

• REST API v1 and v2
• Personal API keys
• Remote services and apps
• Free documentation: this page is free to copy, translate and improve under the GNU FDL 1.3.