What an API is
An API, short for application programming interface, is an agreed way for one piece of software to ask another to do something. The word covers many things, including the functions a code library offers. In maker projects the most common kind is the web API: a service on the internet that your program can ask for data or actions, such as a weather forecast, a train departure time or a way to send a notification.
The useful mental model is a restaurant. You do not walk into the kitchen. You read a menu, place an order in a standard form, and receive a result. The menu is the API’s documentation, the order is the request, and the dish is the response.
Requests and responses
Most web APIs work over HTTP, the same protocol browsers use. Your program sends a request and the server sends back a response. A request typically has four parts:
- An address (URL) that identifies what you are asking about, for example a particular resource such as a city’s forecast.
- A method that says what you want to do. Reading data is usually a GET, creating something is usually a POST, and APIs also commonly define methods for updating and deleting.
- Headers, which carry extra information such as the format you prefer or your credentials.
- Sometimes a body, which holds the data you are sending when creating or updating something.
The response also has parts: a status code, headers, and usually a body. For data services the body is very often JSON, a text format built from named fields, lists and values that almost every programming language can read. Your code parses the JSON into its own data structures and picks out the fields it needs.
Status codes
The status code tells you quickly whether the request worked. They are grouped by their first digit:
- Codes starting with 2 mean success.
- Codes starting with 3 mean you are being redirected elsewhere.
- Codes starting with 4 mean the problem is on your side, such as a bad address, missing credentials or asking for something that does not exist.
- Codes starting with 5 mean the server had a problem.
Checking the code before using the body is a basic habit. A program that assumes every call succeeds will eventually misread an error message as if it were data.
Keys, tokens and authentication
Many services want to know who is calling. The simplest mechanism is an API key, a long string you receive when you register, which you send with each request. Other services use tokens obtained through a sign-in process. Either way, the credential identifies you, lets the provider apply limits and sometimes ties usage to billing.
Treat these credentials like passwords. Do not paste them into code you will publish, and keep them in a configuration file or environment setting instead. The topic of API key secrecy deserves its own attention, but the short version is that anyone who has your key can act as you.
Limits and being a good client
Providers limit how often you can call, usually as a number of requests per period. This is called rate limiting. Exceeding the limit commonly produces an error response, and repeated abuse may lead to a block. The details differ between services, so the documentation is the authority on what is allowed.
Some habits keep a hobby project well-behaved:
- Ask only as often as the data actually changes. A forecast that updates hourly does not need polling every second.
- Store the last good response so your device has something to show if the call fails.
- If you receive an error, wait before retrying, and wait longer after each repeated failure rather than hammering the server.
- Read the service’s terms, since some restrict commercial use or require attribution.
Dealing with failure
Networks are unreliable, and APIs change. Your program should expect timeouts, empty responses and fields that are missing or renamed. Set a sensible timeout so a stalled call does not freeze the whole device, and decide in advance what the device does when the data is unavailable. Good debugging strategy for API problems usually starts with the simplest question: what exactly did I send, and what exactly came back? Logging both the request and the status code answers that most of the time.
Different styles of API
You will meet a few styles. REST-style APIs organise things around addresses and standard methods, and are the most common. Some services offer other styles, such as ones where you describe the data you want in a single query. Others push data to you instead of waiting to be asked. For small sensor networks, a lightweight publish-and-subscribe approach such as MQTT messaging is often a better fit than repeatedly calling a web service, though it solves a somewhat different problem.
A first practical step
Before writing code, try the API by hand. Many services provide examples in their documentation, and you can often make a simple call from a browser or a command-line tool and look at the response. Seeing the real shape of the data makes the code you write afterwards far simpler. Then read the sections on authentication and limits, build the smallest request that works, and add error handling before adding features.
Remember that you depend on someone else’s service. It may change, slow down or disappear, so avoid designing a project that cannot cope without it.