<commit_before>---
layout: post
title: RESTful APIs, the big lie
---
*Why you might benefit from letting this popular paradigm rest in peace.*

![RESTful API, rest in peace](/images/2015-08-10-rip-small.jpg)

### Important update
I have added a **sequel** describing [JSON-Pure APIs](/json-pure)
best practice in detail.  But do please read this first.

### RESTful APIs are awesome, right?
If you have read an internet developer resume or job posting in the past 10
years, then you might be forgiven if you think that **RESTful APIs** are gifts
bestowed from the heavens by The One True Web Developer Deity. RESTful APIs 
are everywhere. Even the marketing folks are pushing them in sales material
intended for CEOs and Human Resources-type folks.

So how good of an idea are RESTful APIs really?  Before we answer that, let's look at where REST came from, and define RESTful APIs.

### Where did REST originate?
REST became popular when it was detailed and promoted by
[Ro<NAME>ing](https://en.wikipedia.org/wiki/Roy_Fielding)
as part of his doctoral dissertation entitled [Architectural Styles
and the Design of Network-based Software
Architectures](https://www.ics.uci.edu/~fielding/pubs/dissertation/top.htm)
in the year 2000.  Roy is well known for his contributions to development of
the web, especially the HTTP specification.

### What are RESTful APIs?
[REST](https://en.wikipedia.org/wiki/Representational_state_transfer) is
Representational State Transfer, an architectural style intended for building
scalable web services. Roy advocated using the request methods he helped define 
in the HTTP standards to impart meaning to HTTP requests.
 
Thus the following HTTP requests all have different meanings when using REST:

- `GET /object/list`
- `POST /object/list`
- `PUT /object/list`

There are only a few HTTP request methods.  The full list is `CONNECT`, `DELETE`,
`GET`, `HEAD`, `OPTIONS`, `PATCH`, `POST`, `PUT`, and `TRACE`.  You may be forgiven if you've never heard of a few of these, as some are almost never supported by
client or server software.

Roy also advocated that HTTP response codes he helped define be used to communicate
the meaning of the response. There are ~38 HTTP response codes.  Below is a complete list. I've shortened a few titles in the interest of space:

| Method | Method |
|:----------------------|:-------------------------|
| 200 OK              | 201 Created            |
| 202 Accepted        | 203 Not authorized     |
| 204 No content      | 205 Reset content      |
| 206 Partial content |                        |
| 300 Multiple choice    | 301 Moved permanently  |
| 302 Found              | 303 See other          |
| 304 Not modified       | 306 (unused)           |
| 307 Temporary redirect |                        |
| 400 Bad request             | 401 Unauthorized             |
| 402 Payment required        | 403 Forbidden                |
| 404 Not found               | 405 Method not allowed       |
| 406 Not acceptable          | 407 Proxy auth required      |
| 408 Timeout                 | 409 Conflict                 |
| 410 Gone                    | 411 Length required          |
| 412 Preconditions failed    | 413 Request entity too large |
| 414 Requested URI too long  | 415 Unsupported media        |
| 416 Bad request range       | 417 Expectation failed       |
| 500 Server error    | 501 Not implemented     |
| 502 Bad gateway     | 503 Service unavailable |
| 504 Gateway timeout | 505 Bad HTTP version    |

The meaning of such an API transaction over HTTP is therefore at the minimum the result of

- the HTTP request method verb, e.g `GET`
- the request address, e.g. `/object/list`<commit_msg>+fixed 203 response code meaning<commit_after>---
layout: post
title: RESTful APIs, the big lie
---
*Why you might benefit from letting this popular paradigm rest in peace.*

![RESTful API, rest in peace](/images/2015-08-10-rip-small.jpg)

### Important update
I have added a **sequel** describing [JSON-Pure APIs](/json-pure)
best practice in detail.  But do please read this first.

### RESTful APIs are awesome, right?
If you have read an internet developer resume or job posting in the past 10
years, then you might be forgiven if you think that **RESTful APIs** are gifts
bestowed from the heavens by The One True Web Developer Deity. RESTful APIs 
are everywhere. Even the marketing folks are pushing them in sales material
intended for CEOs and Human Resources-type folks.

So how good of an idea are RESTful APIs really?  Before we answer that, let's look at where REST came from, and define RESTful APIs.

### Where did REST originate?
REST became popular when it was detailed and promoted by
[Roy Fielding](https://en.wikipedia.org/wiki/Roy_Fielding)
as part of his doctoral dissertation entitled [Architectural Styles
and the Design of Network-based Software
Architectures](https://www.ics.uci.edu/~fielding/pubs/dissertation/top.htm)
in the year 2000.  Roy is well known for his contributions to development of
the web, especially the HTTP specification.

### What are RESTful APIs?
[REST](https://en.wikipedia.org/wiki/Representational_state_transfer) is
Representational State Transfer, an architectural style intended for building
scalable web services. Roy advocated using the request methods he helped define 
in the HTTP standards to impart meaning to HTTP requests.
 
Thus the following HTTP requests all have different meanings when using REST:

- `GET /object/list`
- `POST /object/list`
- `PUT /object/list`

There are only a few HTTP request methods.  The full list is `CONNECT`, `DELETE`,
`GET`, `HEAD`, `OPTIONS`, `PATCH`, `POST`, `PUT`, and `TRACE`.  You may be forgiven if you've never heard of a few of these, as some are almost never supported by
client or server software.

Roy also advocated that HTTP response codes he helped define be used to communicate
the meaning of the response. There are ~38 HTTP response codes.  Below is a complete list. I've shortened a few titles in the interest of space:

| Method                     | Method                       |
|:---------------------------|:-----------------------------|
| 200 OK                     | 201 Created                  |
| 202 Accepted               | 203 Non-Authoritative Info   |
| 204 No content             | 205 Reset content            |
| 206 Partial content        |                              |
| 300 Multiple choice        | 301 Moved permanently        |
| 302 Found                  | 303 See other                |
| 304 Not modified           | 306 (unused)                 |
| 307 Temporary redirect     |                              |
| 400 Bad request            | 401 Unauthorized             |
| 402 Payment required       | 403 Forbidden                |
| 404 Not found              | 405 Method not allowed       |
| 406 Not acceptable         | 407 Proxy auth required      |
| 408 Timeout                | 409 Conflict                 |
| 410 Gone                   | 411 Length required          |
| 412 Preconditions failed   | 413 Request entity too large |
| 414 Requested URI too long | 415 Unsupported media        |
| 416 Bad request range      | 417 Expectation failed       |
| 500 Server error           | 501 Not implemented          |
| 502 Bad gateway            | 503 Service unavailable      |
| 504 Gateway timeout        | 505 Bad HTTP version         |

The meaning of such an API transaction over HTTP is therefore at the minimum the result of

- the HTTP request method verb, e.g `GET`
- the request address, e.g. `/object/list`
{'fraction_non_alphanumeric': 0.08082010582010582, 'fraction_numerical': 0.034788359788359785, 'mean_word_length': 2.4956079519186316, 'pattern_counts': {'":': 0, '<': 4, '<?xml version=': 0, '>': 4, 'https://': 6, 'lorem ipsum': 0, 'www.': 2, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 4, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '2617132', 'n_tokens_mistral': 2195, 'n_tokens_neox': 1817, 'n_words': 948}