REST API Design: Principles and Output Format
💡 Summary (TL;DR):
- Intro: When you're architecting a shared backend to serve web apps, mobile devices, and other third-party services, RESTful API design standards are vital.
- Goal of the series: To standardize the core building blocks of an API—output format, URI structure, security, error handling, and authentication.
- Core choices: Unless you have a specific constraint, JSON is the data-transfer format best suited to modern web standards.
Who Needs to Learn the Nuances of RESTful API Design? Who Is This For?
If you're a solo developer building a small-to-medium, traditional website, you won't need a REST API; you can carry on with the monolithic approach you already know.
But if you need to design a shared backend that your website, your mobile devices, and perhaps other external services will all consume data from, then you do need to learn the nuances of REST API design.
Because this is such a broad topic, it's far more useful to break it down into logical pieces.
REST API HTTP Methods and Their Purposes
| HTTP Method | Operation (CRUD) | Description | Safe? | Idempotent? |
|---|---|---|---|---|
| GET | Read | Queries the specified resource or collection. | Yes | Yes |
| POST | Create | Creates a new resource. | No | No |
| PUT | Update | Completely replaces the specified resource with a new one. | No | Yes |
| PATCH | Update (Partial) | Updates only specific fields of the resource. | No | No |
| DELETE | Delete | Deletes the specified resource. | No | Yes |
The Full Series
We'll tackle RESTful API design piece by piece under the headings below. The first two are covered in this article; you can reach the rest through the links provided:
- REST API Basics
- What Should the REST API Output Format Be?
- What Should the REST API URI Structure Be?
- What Is HATEOAS in REST API?
- How Do You Authenticate a REST API? (Authentication)
- How Do You Handle Errors in a REST API? (Error Handling)
- How Do You Secure a REST API? (Security)
- How Do You Document and Test a REST API?
- Sample REST API Project
I'll be honest: I'm not the original source of most of this. Until a few years ago, I was only a consumer of APIs. When the day finally came that I had to write one myself, I did a lot of research and took plenty of notes—and what you'll read here is those notes, compiled and tidied up, with a bit of my own experience mixed in.
Different Approaches
For most of the topics I'll cover here, there can be different approaches or methods. In fact, if you study the industry giants, you'll find points that don't line up with the standards here—they've adopted their own internal practices. What I'm sharing are the best practices I arrived at after my own research and experimentation: "if I were designing a REST API, this is how I'd do it."
Architecture-Independent Design
The programming language, database, or server infrastructure you use sits outside API design itself; those are decided by budget, team skill set, and the needs of your existing system. So I'll skip the coding and server side and focus directly on the parts that concern the API interface design.
In an earlier piece, RESTful API Components, I laid out my personal technology preferences on this subject.
REST API Basics
With a RESTful API design, you expose specific resources and make them available for clients to use. In monolithic sites, we fire AJAX queries at the backend and update the UI based on the results; a RESTful API works the same way—any client (web, mobile, IoT) sends us a request over HTTP, and we return a response in a standard language that client can understand.
Your API exposes, creates, updates, and deletes resources (for example, author) or collections of those resources (authors).
To work with these resources, you send requests to predefined endpoint addresses using the classic HTTP methods like GET, POST, PUT, PATCH, and DELETE.
Honestly, I wish every project were just a pure RESTful API. A standard data model comes in, you run operations on it, and you return output in a standard format. It's a far cleaner and less painful process than wrestling with a full-stack monolithic application. :)
Output Format
Your API's output format can be JSON, CSV, XML, RSS, or HTML. In a software world where requirements are limitless, the solutions for them are no doubt just as varied. But if you're designing a modern, publicly available REST API, you'll probably go with JSON.
Unless you have a specific or restrictive system constraint, I strongly recommend using JSON as your output format—for its light weight and its perfect fit with the JavaScript ecosystem.
In the next article of the series, we'll focus on how endpoint addresses (URIs) should be defined in RESTful APIs:
Changes Made in This Article
- 11.05.2022: Article summary revised.
- 21.06.2026: Standardized REST API brand naming, fixed spelling errors (infrastructure, methods, testing, etc.) and repeated words within sentences. Cleaned up duplicate punctuation at the ends of sentences. Enriched the article with a TL;DR summary panel for the intro and a reference table showing the CRUD/Idempotent properties of the HTTP methods.
