Explain like I'm five · SW Eng

What is an Open API?

Open API, told as a story about a reading room opened with one standard request form, instead of everyone calling in separately to ask.

could I take a look at that data?um... let me explain the form againevery requester asks differently, so it's explained from scratch each time

To see our data, outsiders have to call in and ask separately every time.Every requester asks differently, so it's explained from scratch each time.

every request form looks differentthe editor has to check each one by hand — slow going

Every form looks different, so checking takes a long time.The editor has to check each one by hand — slow going.

Open API = a reading room whose request form is published as a standardSTANDARD REQUEST FORMwhat: topic and scopehow: in the fixed formatget it: automatically, right awayfill out this one form, and anyone can borrow the data the same way

An Open API is a reading room whose request form is published as a standard.Fill out this one form, and anyone can borrow the data the same way.

Standardize the formthe request format is fixed and published
Open a reading deskanyone using the form gets served
Issue a usage keybut who's borrowing is still tracked
Set the usage scopehow much can be borrowed is set in advance
THE REQUEST FORM SPECrequest fields: which data, under what conditionsresponse format: comes back in a fixed shapeusage key: issued once your request is approvedread just this spec, and you can request data without seeing our internal code

One spec sheet for the request form lets anyone ask for data.The spec writes down in advance what to ask for, how, and what comes back.

the reading room is openthe front gate (API gateway) handles the crowd of requestsopening the reading room and managing the line are different jobs

Opening the reading room and managing the line are different jobs.Open API is the policy of what to make public — handling the flood of requests itself is the job of → the front gate information booth.

In one breath

Open API = instead of everyone calling in separately, publishing a standard request form in advance so anyone can borrow the data the same way.

An Open API is both a policy and a technical approach: a public institution or company publishes its data or functionality externally through a standardized spec (request format, response format, authentication method), so that anyone following that spec can use it. It's documented with a spec standard like OpenAPI (Swagger), with usage keys and quotas managing how much gets used. Korea's public data portal 'Open API' is a well-known example.

When grown-ups say it

Open API
The reading room opened with one standard form. Anyone can request data the same way.
API Specification
The document that writes down the request form itself. Written using a standard like OpenAPI (Swagger).
API Key
The key that confirms who's borrowing. Issued once your application is approved.
Public Data Portal
The reading room the government opened, gathering many agencies' data. Open APIs from many agencies are gathered here.
Data Standardization
Making the response shape the same for everyone. Even with a form, responses in mismatched shapes are hard to use.
API Gateway
The booth that actually handles the flood of requests. Open API is the policy; the gateway is the infrastructure that handles the requests → the front gate information booth.
External Interface File
The connection point for referencing another publisher's data. This kind of link gets counted too, when sizing up the work → the ruler that measures functions, not pages.
Usage Quota
The limit on how much one key can borrow in a set period, often a day. Go over the limit, and that key is done for the period.
Next story
The Writer's Locked Drawer →
Want another term as a picture book? Request →