What Is a REST API

An API in one sentence

An API — an application programming interface — is a contract that lets one program ask another program to do something or hand over data. Instead of a person clicking buttons in a browser, your code sends a request and receives a structured reply it can read automatically, with no human in the loop.

A web API exposes that contract over the same network technology as websites: HTTP. Your integration sends a request to a URL, a server somewhere processes it, and a response comes back. Because the rules are written down and stable, you can build software against them with confidence that they will behave the same way next week as they do today.

This predictability is the whole point. A good API is boring in the best sense — it does exactly what its documentation says, every single time, so you can automate against it without nasty surprises.

What REST actually means

REST stands for Representational State Transfer. It is not a protocol or a library you install — it is a set of design constraints first described by Roy Fielding in 2000. The key idea is that everything your API cares about is modelled as a resource: a customer, an invoice, a recovery case, a document.

Each resource has an address (a URL) and one or more representations — usually JSON documents that describe its current state. You never manipulate the resource on the server directly; instead you exchange representations of it back and forth. Reading, creating, updating, and deleting are all expressed through a small set of standard HTTP methods rather than bespoke commands invented for each endpoint.

Because every interaction follows the same handful of rules, REST APIs are unusually easy to learn once and then reuse everywhere you meet them.

Why build on HTTP

REST leans on HTTP quite deliberately. The web has already solved a great many hard problems — caching, authentication, status reporting, content negotiation, redirection — and REST reuses that mature machinery instead of reinventing it from scratch. When a request succeeds you get a 2xx status; when something is wrong you get a 4xx or 5xx code with a well-defined meaning that your code can branch on.

Statelessness is another pillar. Each request carries everything the server needs to handle it, so the server keeps no memory of previous calls between requests. This makes the system simpler to scale horizontally and far easier to reason about, because no request quietly depends on a hidden session left behind by an earlier one. Every call stands on its own two feet.

A quick example

Fetching a resource looks like an ordinary web request. The method goes first, then the path, then a few headers describing what you want back and in which format:

GET /v1/cases/12345 HTTP/1.1
Host: api.example.com
Accept: application/json

The server replies with a status line and a JSON body that represents the current state of that case. To create something new you would send a POST with a body describing it; to remove it, you would send a DELETE to the same address. The pattern stays consistent across every resource, and that consistency is exactly what makes REST pleasant to work with day after day. Once you have written one call by hand, the next ones feel familiar rather than foreign.

Where Merion fits

Merion's platform exposes a REST API secured with OpenID Connect, so the concepts covered here apply directly to every call you will make against it. The same resources, methods, and status codes you learn from any general REST tutorial carry across with very little translation, which means your existing instincts transfer cleanly to this API.

If you are ready to dig in, the developer portal walks through getting started, authentication, and your first request step by step. For the request side of the REST contract — the verbs that drive every call — read HTTP methods explained next, and you will have the foundations you need to start building.