Learn REST APIs

An API (Application Programming Interface) is like a menu at a restaurant. The menu provides a list of dishes you can order, along with a description of each dish. When you specify what you'd like to order, the kitchen (the system) prepares it and serves it back to you. In the same way, an API lists operations that developers can use, along with a description of what they do.

Think of it this way: when you use a mobile app, the app connects to the Internet and sends data to a server. The server then retrieves that data, interprets it, performs the necessary actions, and sends it back to your phone. The app then interprets that data and presents you with the information you wanted in a readable way. This is what an API does - it's the messenger that takes your request and tells the system what you want to do, then returns the response back to you.

HTTP methods tell the server what action you want to perform. Think of them as verbs that describe what you're trying to do:

Most of our API endpoints use GET because they're retrieving information. Let's see a GET request in action:

Every API response includes a status code that tells you whether your request was successful or not. These are three-digit numbers that fall into different categories:

Let's see different status codes in action:

APIs communicate using JSON (JavaScript Object Notation), which is a way of formatting data that's easy for both humans and computers to read. JSON uses key-value pairs, similar to a dictionary.

Our API responses follow a consistent structure:

Query parameters let you customize your API requests. They're added to the URL after a question mark (?). You can add multiple parameters by separating them with ampersands (&).

For example: /api/states?state=ca&format=minimal

Use the builder below to experiment with different parameters:

Some APIs require authentication to ensure only authorized users can access them. Our API uses API keys, which are like passwords that identify you. API keys are sent in the request headers.

Why use API keys?

• Higher rate limits (more requests allowed)
• Access to premium features
• Better tracking and analytics

To use an API key, you include it in the request headers like this:

Rate limiting prevents abuse by limiting how many requests you can make in a certain time period. Think of it like a speed limit on a highway - it keeps everyone safe and ensures fair usage.

Rate limit information is included in the response headers. Check the “Response Headers” section when you make a request to see your current rate limit status.

CORS (Cross-Origin Resource Sharing) is a security feature that controls which websites can make requests to an API from a browser. It's like a bouncer at a club checking IDs.

Why does it matter? Browsers have a “same-origin policy” that blocks requests from one website to another unless the server explicitly allows it. CORS headers tell the browser which origins are allowed.

Our API includes CORS headers in responses, which you can see when you make a request. Look for headers like:

Make a request below and expand the “Response Headers” section to see CORS headers in action:

Now that you understand the basics, try building your own API requests! Use the parameter builder below to experiment with different combinations.