API

How an API works

An API is a published way for one program to ask another for data, or to ask it to do something. The ask is a request. What comes back is a response. This page asks Wikidata for data centers and leaves both exchanges where you can read them.

Round trip

A request, then a response

A client builds a request. It names a method, a URL, and a few headers. Sometimes it adds a body. A server reads that and sends a response: a status code, headers, and often a body. Then that exchange is over.

The demo further down is the round trip twice. Your browser calls GET /api/data-centers on this site. This site calls Wikidata. Both exchanges are shown with the status, the headers, the timing, and the body.

1 · Client
The browser, or this site’s server acting for the browser.
2 · Request
Method, URL, headers, and a body when the method needs one.
3 · Response
Status, headers, and the body you render or read.

Methods

The verb says what you want done

These four cover most APIs. This demo only reads, so every call is a GET.

GET

Read

Ask for a copy. A search is a GET. Sending it again should leave the server’s data as it was.

POST

Submit

Send something new, or ask the server to do a job. The contact form on this site is a POST.

PUT

Replace

Put a new copy in place of what is already stored at that URL.

DELETE

Remove

Ask the server to delete the resource at that URL.

Status

The code says how it went

The first digit is the family. 2 means success, 3 means look elsewhere, 4 means the request has a problem, 5 means the server failed.

200 OK

The request worked. The body is the answer.

301 Moved

The resource has a new URL. The Location header names it. 302 is a temporary move.

400 Bad Request

The server could not understand the request. A search field with a character this page refuses gets a 400.

401 Unauthorized

The request needs credentials. The server does not know who is calling.

403 Forbidden

The server understood the request and refuses it.

404 Not Found

That URL does not point at a resource.

429 Too Many Requests

The caller is going too fast. This page slows itself down so a crowd of searches shares a few calls.

500 Server error

The server failed on its side. 502 and 504 mean a server in the middle, or this site, did not get a usable answer.

Headers

Notes in the margin

Headers are lines of metadata around the body. A request can send Accept: application/json to name a format it can read, and User-Agent to say who is calling. A response can send Content-Type to name the format of the body, and Cache-Control to say how long a copy may be kept.

This site sends a User-Agent that names the site and this page. Wikidata asks callers to do that. The key, if an API needed one, would be a header too, and it would stay on the server.

Query string

Parameters narrow a GET

The part of a URL after ? is a set of keys and values. country, city, and name are all optional on /api/data-centers. Leaving them blank returns the newest data centers. Filling any in narrows the results. /api/data-centers?country=US&city=Dallas&name=DataBank sends all three.

This page puts your search on that path. The server turns it into a Wikidata query and places the text in Wikidata’s query parameter. That URL is long. The panel shows the real one.

Authentication

Who is allowed to ask

None

Anyone may read. Wikidata’s query service works this way for a search like the one below. There is no key to copy and no account to sign in.

API key

A secret string, usually in a header such as Authorization. The server checks the string, then does the work. A page should keep the key on the server. The browser never needs to see it.

OAuth

A short handshake. You approve an app, and the app receives a token that expires. Later requests carry the token. You can revoke it without changing your password.

Body

The formats an API speaks

The Content-Type header names which of these the body is. The demo asks for JSON and prints the body it gets.

JSON

application/json

Text made of objects and lists. Wikidata returns this when the request asks for it. The panel below is that body.

XML

application/xml

Text made of tags. A lot of older APIs still answer in XML. The same facts, a different spelling.

CSV

text/csv

Rows of values separated by commas. A spreadsheet download is often CSV. Easy to scan, awkward for nested facts.

Form data

application/x-www-form-urlencoded

How a browser submits a form. One kind looks like a query string in the body. multipart/form-data can carry a file.

Shapes

REST, GraphQL, and webhooks

REST

Many URLs, one resource on each. The HTTP method says what to do. A facility might live at /facilities/1234. GET reads it. DELETE removes it.

GraphQL

Usually one URL. The request body names the fields the client wants, and the response is shaped like that request. The client asks for a name and a city, and skips the rest.

Webhooks

The other direction. You give a service your URL, and it POSTs to you when something happens, so you do not have to keep asking.

Wikidata’s query service is one URL that runs a query, closer to that single-endpoint idea than to a resource-per-URL design. The envelope is still ordinary HTTP, which is what the panel measures.

Collection Lab watches this browser’s own requests. This page watches a request this server makes for you.

Search data centers

Wikidata items that are an instance of data center (Q671224). The list is the response, newest edit first. Updated is when the Wikidata item was last edited. Opened is the date on the record, when it has one. A year stored as 1 January is often just a year. The search terms go to this site’s server, which calls Wikidata with those terms and this site’s User-Agent.

GET /api/data-centers

Parameters

Every filter is optional. Leaving them blank returns the newest data centers. Filling any in narrows the results.

Parameter	Required	What it matches
country	Optional	Two letters match the ISO code, such as US. A longer value matches the English country name.
city	Optional	The place Wikidata stored, which may be a city, a district, or a region.
name	Optional	Words from the facility name.

Request examples

No filters. The newest data centers.
```
GET /api/data-centers
```

Any filled field narrows that list.

GET /api/data-centers?country=US&city=Dallas&name=DataBank

Response filters

The live search below writes this object. A blank country stays as an empty string. Blank city and name are left out.

{
  "filters": {
    "country": ""
  }
}

Facilities

Calling this site, which calls Wikidata…

Browser → this site

The request this page sent

Sending the GET…

This site → Wikidata

The upstream call

Waiting for this server to call Wikidata…

Data from Wikidata, released under CC0 1.0. Licensing. User-Agent policy. Each distinct search is kept on this server for about 10 minutes, and a repeat of that search reuses the saved response.

Recommended next

Why these picks

Reading path transitions…