# How to (and how not to) design REST APIs · stickfigure

<https://github.com/stickfigure/blog/wiki/How-to-%28and-how-not-to%29-design-REST-APIs>

- Host: [github.com](https://links.thingelstad.xyz/hosts/github.com/)
- Saved: November 2, 2023 (2023-11-02T11:38:37Z)
- Record: https://links.thingelstad.xyz/links/744f19d9521c/
- JSON: https://links.thingelstad.xyz/links/744f19d9521c.json

## What Jamie wrote

Schnitzer with design suggestions for REST APIs. This is pretty straightforward, and I that it stays pretty simple and has a clear focus on usability. 

> 1. DO use plural nouns for collections
> 2. DON'T add unnecessary path segments
> 3. DON'T add .json or other extensions to the url
> 4. DON'T return arrays as top level responses
> 5. DON'T return map structures
> 6. DO use strings for all identifiers
> 7. DO prefix your identifiers
> 8. DON'T use 404 to indicate "not found"
> 9. BE consistent
> 10. DO use a structured error format
> 11. DO provide idempotence mechanisms

Of all of them, I think 9 is one of the most important.

## Facts

- Kind: [Repository](https://links.thingelstad.xyz/kinds/repository/)

## Appears in

- [WT268: Weekly Thing 268 / Schema, Achtung, Gamification](https://weekly.thingelstad.com/archive/268/), Notable

## Same host

- [How GitHub Engineering communicates](https://links.thingelstad.xyz/links/7d8eea3ee147/) (github.com, October 16, 2023)
- [pypipe: Python pipe command line tool](https://links.thingelstad.xyz/links/089a85bdb994/) (github.com, October 25, 2023)
- [tailspin: 🌀 A log file highlighter](https://links.thingelstad.xyz/links/ef8eeffa68db/) (github.com, November 6, 2023)
- [standard-webhooks](https://links.thingelstad.xyz/links/47d65d5baf4d/) (github.com, December 11, 2023)
- [qsv: CSVs sliced, diced & analyzed.](https://links.thingelstad.xyz/links/2a5bdff70645/) (github.com, January 1, 2024)

## Saved the same week

- [Microsoft’s 2023 Diversity and Inclusion Report - The Official Microsoft Blog](https://links.thingelstad.xyz/links/acff027db2ce/) (blogs.microsoft.com, November 1, 2023)
- [Rob Pike's 5 Rules of Programming](https://links.thingelstad.xyz/links/921b12daa3cf/) (users.ece.utexas.edu, November 2, 2023)
- [How Bear does analytics with CSS | Herman's blog](https://links.thingelstad.xyz/links/bf21b3d2eb61/) (herman.bearblog.dev, November 2, 2023)
- [Life Lessons from the Death Bed – Isonomia Quarterly](https://links.thingelstad.xyz/links/455a41ddb5f8/) (isonomiaquarterly.com, November 2, 2023)
- [The Omni Show: GTD Focus President Meg Edwards Returns](https://links.thingelstad.xyz/links/c5995837a801/) (omnigroup.com, November 2, 2023)

## Elsewhere

- Wayback Machine: https://web.archive.org/web/*/https://github.com/stickfigure/blog/wiki/How-to-%28and-how-not-to%29-design-REST-APIs