Terms and Concepts for APIs¶
API¶
An API is an application programming interface. It means a lot of things, but in practice it's often "a web page that contains data a computer can read." On this page we'll often use the PokeAPI pokemon API as an example.
Endpoint¶
And endpoint is a URL you can visit for information, or the pattern that a URL would have.
For example, https://pokeapi.co/api/v2/pokemon/{id or name}. You'll replace the {id or name} part with some piece of information, like the name of a pokemon. If you wanted the information for Pikachu, you'd visit https://pokeapi.co/api/v2/pokemon/pikachu. Some more examples:
| endpoint or URL | description |
|---|---|
/api/v2/pokemon/{id or name} |
example endpoint, you'll need to fill in the {id or name} |
/api/v2/pokemon/pikachu |
pikachu's information, because his name is pikachu and we filled in the blanks for the endpoint |
/api/v2/pokemon/pikachu |
pikachu's information, because his id is (apparently) 55 and we filled in the blanks for the endpoint |
Query strings and parameters¶
The query string (or querystring) is the variables-y part of the URL. It's always after a ?. For example:
Along with the specific URL we're visiting, we're sending along two extra bits of information, called parameters:
limitis 10offsetis 5
The query string is separted from the URL by a question mark ?, while each separate parameter is separated by an ampersand &. You can have a million of them if you'd like:
REST or RESTful¶
RESTful APIs a kind of APIs that have very nice URLs (the reality is more complicated, but don't worry about it). For example, if we want information about pokemon, we can approach it two separate ways:
| URL | information |
|---|---|
| https://pokeapi.co/api/v2/pokemon/pikachu | Just pikachu |
| https://pokeapi.co/api/v2/pokemon | All pokemon |
Longer URLs ahve more specific information, while shorter URLs have less information. A non-RESTful API would probably have a URL something like https://pokeapi.co/api/v2/pokemon?name=pikachu, where pikachu's name is sent as part of the query string.
Pagination, offset, limits¶
Pagination is when data is split across multiple pages.
For example, if we look for a list of all pokemon, we might visit this url:
But when we see the results... it definitely isn't all of the pokemon!
{
"count": 1154,
"next": "https://pokeapi.co/api/v2/pokemon?offset=20&limit=20",
"previous": null,
"results": [
{ "name": "bulbasaur", "url": "https://pokeapi.co/api/v2/pokemon/1/" },
{ "name": "ivysaur", "url": "https://pokeapi.co/api/v2/pokemon/2/" },
{ "name": "venusaur", "url": "https://pokeapi.co/api/v2/pokemon/3/" },
{ "name": "charmander", "url": "https://pokeapi.co/api/v2/pokemon/4/" },
{ "name": "charmeleon", "url": "https://pokeapi.co/api/v2/pokemon/5/" },
{ "name": "charizard", "url": "https://pokeapi.co/api/v2/pokemon/6/" },
{ "name": "squirtle", "url": "https://pokeapi.co/api/v2/pokemon/7/" },
{ "name": "wartortle", "url": "https://pokeapi.co/api/v2/pokemon/8/" },
{ "name": "blastoise", "url": "https://pokeapi.co/api/v2/pokemon/9/" },
{ "name": "caterpie", "url": "https://pokeapi.co/api/v2/pokemon/10/" },
{ "name": "metapod", "url": "https://pokeapi.co/api/v2/pokemon/11/" },
{ "name": "butterfree", "url": "https://pokeapi.co/api/v2/pokemon/12/" },
{ "name": "weedle", "url": "https://pokeapi.co/api/v2/pokemon/13/" },
{ "name": "kakuna", "url": "https://pokeapi.co/api/v2/pokemon/14/" },
{ "name": "beedrill", "url": "https://pokeapi.co/api/v2/pokemon/15/" },
{ "name": "pidgey", "url": "https://pokeapi.co/api/v2/pokemon/16/" },
{ "name": "pidgeotto", "url": "https://pokeapi.co/api/v2/pokemon/17/" },
{ "name": "pidgeot", "url": "https://pokeapi.co/api/v2/pokemon/18/" },
{ "name": "rattata", "url": "https://pokeapi.co/api/v2/pokemon/19/" },
{ "name": "raticate", "url": "https://pokeapi.co/api/v2/pokemon/20/" }
]
}
Oftentimes APIs that give out a lot of data split the data into multiple pages, and require special parametres to give you more or less data, or start on the 4th page, or wathever. This often uses limit to say how many you want, and offset to say how far from the first result. For example:
Show me 20 pokemon, but skip the first 20
Show me 100 pokemon