rest posts - idmontie's Portfolio

/*@jsxRuntime automatic @jsxImportSource react*/
const {Fragment: _Fragment, jsx: _jsx, jsxs: _jsxs} = arguments[0];
function _createMdxContent(props) {
  const _components = Object.assign({
    p: "p",
    em: "em",
    h2: "h2",
    ul: "ul",
    li: "li",
    a: "a",
    strong: "strong",
    pre: "pre",
    code: "code",
    h3: "h3"
  }, props.components);
  return _jsxs(_Fragment, {
    children: [_jsx(_components.p, {
      children: "This post was originally on a blog I started for creating web applications. This post goes into RESTful interfaces and how to design them."
    }), "\n", _jsxs(_components.p, {
      children: ["RESTful APIs are a common way for applications to be able to communicate with each other.  An important part about RESTful APIs is that they are ", _jsx(_components.em, {
        children: "consistent"
      }), ".  Naming, verbage, actions, and errors should be consistent within your API and with how other APIs behave."]
    }), "\n", _jsx(_components.p, {
      children: "Here are some tips and questions that you should ask yourself when developing an API."
    }), "\n", _jsx(_components.h2, {
      children: "Are you using PUT and POST correctly?"
    }), "\n", _jsx(_components.p, {
      children: "Both PUT and POST can be used for creating. You do not need to support both PUT and POST. Consider the following design decisions:"
    }), "\n", _jsxs(_components.ul, {
      children: ["\n", _jsx(_components.li, {
        children: "Do you name your URL objects you create explicitly, or let the server decide? If you name them then use PUT. If you let the server decide then use POST."
      }), "\n", _jsx(_components.li, {
        children: "PUT is idempotent, so if you PUT an object twice, it has no effect. This is a nice property, so I would use PUT when possible."
      }), "\n", _jsx(_components.li, {
        children: "You can update or create a resource with PUT with the same object URL"
      }), "\n", _jsx(_components.li, {
        children: "With POST you can have 2 requests coming in at the same time making modifications to a URL, and they may update different parts of the object."
      }), "\n"]
    }), "\n", _jsxs(_components.p, {
      children: ["See ", _jsx(_components.a, {
        href: "http://stackoverflow.com/questions/630453/put-vs-post-in-rest",
        children: "this StackOverflow question for more information"
      }), "."]
    }), "\n", _jsx(_components.h2, {
      children: "Are you using appropriate verbs?"
    }), "\n", _jsx(_components.p, {
      children: "When making a REST API, your verbs are your request types, not actual verbs in your URL!  Your URLs should use nouns, not verbs!  Remember to use the plural form for multiple results."
    }), "\n", _jsx(_components.p, {
      children: "Use your URLs to specify your objects.  Here are some examples of RESTful style requests:"
    }), "\n", _jsx(_components.p, {
      children: _jsx(_components.strong, {
        children: "Obtain 1 Question"
      })
    }), "\n", _jsx(_components.pre, {
      children: _jsx(_components.code, {
        children: "GET /questions/<question>\n"
      })
    }), "\n", _jsx(_components.p, {
      children: _jsx(_components.strong, {
        children: "Obtain All Questions"
      })
    }), "\n", _jsx(_components.pre, {
      children: _jsx(_components.code, {
        children: "GET /questions\n"
      })
    }), "\n", _jsx(_components.p, {
      children: _jsx(_components.strong, {
        children: "Append/Update Question"
      })
    }), "\n", _jsx(_components.pre, {
      children: _jsx(_components.code, {
        children: "POST /questions/<existing_question>\n"
      })
    }), "\n", _jsx(_components.p, {
      children: _jsx(_components.strong, {
        children: "Create a New Question"
      })
    }), "\n", _jsx(_components.pre, {
      children: _jsx(_components.code, {
        children: "PUT /questions/<new_question>\n"
      })
    }), "\n", _jsx(_components.p, {
      children: _jsx(_components.strong, {
        children: "Overwrite a Question"
      })
    }), "\n", _jsx(_components.pre, {
      children: _jsx(_components.code, {
        children: "PUT /questions/<existing_question>\n"
      })
    }), "\n", _jsx(_components.p, {
      children: _jsx(_components.strong, {
        children: "Delete Question"
      })
    }), "\n", _jsx(_components.pre, {
      children: _jsx(_components.code, {
        children: "DELETE /questions/<existing_question>\n"
      })
    }), "\n", _jsx(_components.h2, {
      children: "Nested Resources should be exenstions, not entirely different queries"
    }), "\n", _jsx(_components.p, {
      children: "If you want to get answers to a question, using the above examples as a starting point, the URL should be:"
    }), "\n", _jsx(_components.pre, {
      children: _jsx(_components.code, {
        children: "GET /questions/1/answers\n"
      })
    }), "\n", _jsx(_components.p, {
      children: "This is nested routing and it helps for a cleaner design."
    }), "\n", _jsx(_components.h2, {
      children: "Do you have a plan to version your API?"
    }), "\n", _jsx(_components.p, {
      children: "There are different ways to version your API, but it's nice to plan ahead in order for consumers of your API to be prepared."
    }), "\n", _jsxs(_components.p, {
      children: [_jsx(_components.a, {
        href: "https://developer.github.com/v3/media/#request-specific-version",
        children: "Github uses"
      }), " the ", _jsx(_components.code, {
        children: "Accept"
      }), " HTTP header to pass the desired version to the API."]
    }), "\n", _jsxs(_components.p, {
      children: ["Another less common method is to version the application in the URL: ", _jsx(_components.code, {
        children: "/api/v1/..."
      }), "."]
    }), "\n", _jsx(_components.h2, {
      children: "Paging"
    }), "\n", _jsxs(_components.p, {
      children: ["Large result sets should be paginated, you can use ", _jsx(_components.a, {
        href: "https://developer.github.com/guides/traversing-with-pagination/",
        children: "the Github method"
      }), " for indicated next and previous pages of results using the ", _jsx(_components.code, {
        children: "Link"
      }), " HTTP header."]
    }), "\n", _jsx(_components.h2, {
      children: "HTTP Status Codes"
    }), "\n", _jsxs(_components.p, {
      children: [_jsx(_components.a, {
        href: "https://bourgeois.me/rest/",
        children: "This list of HTTP Status codes"
      }), " and their meaning is very helpful for knowing what HTTP Status your API should be returning.  It has been duplicated here as a backup:"]
    }), "\n", _jsx(_components.h3, {
      children: "Success codes"
    }), "\n", _jsxs(_components.ul, {
      children: ["\n", _jsxs(_components.li, {
        children: [_jsx(_components.code, {
          children: "201 Created"
        }), " should be used when creating content (INSERT)"]
      }), "\n", _jsxs(_components.li, {
        children: [_jsx(_components.code, {
          children: "202 Accepted"
        }), " should be used when a request is queued for background processing (async tasks),"]
      }), "\n", _jsxs(_components.li, {
        children: [_jsx(_components.code, {
          children: "204 No Content"
        }), " should be used when the request was properly executed but no content was returned (a good example would be when you delete something)."]
      }), "\n"]
    }), "\n", _jsx(_components.h3, {
      children: "Client error codes"
    }), "\n", _jsxs(_components.ul, {
      children: ["\n", _jsxs(_components.li, {
        children: [_jsx(_components.code, {
          children: "400 Bad Request"
        }), " should be used when there was an error while processing the request payload (malformed JSON, for instance)."]
      }), "\n", _jsxs(_components.li, {
        children: [_jsx(_components.code, {
          children: "401 Unauthorized"
        }), " should be used when a request is not authenticiated (wrong access token, or username or password)."]
      }), "\n", _jsxs(_components.li, {
        children: [_jsx(_components.code, {
          children: "403 Forbidden"
        }), " should be used when the request is successfully authenticiated (see 401), but the action was forbidden."]
      }), "\n", _jsxs(_components.li, {
        children: [_jsx(_components.code, {
          children: "406 Not Acceptable"
        }), " should be used when the requested format is not available (for instance, when requesting an XML resource from a JSON only server)."]
      }), "\n", _jsxs(_components.li, {
        children: [_jsx(_components.code, {
          children: "410 Gone Should"
        }), " be returned when the requested resource is permenantely deleted and will never be available again."]
      }), "\n", _jsxs(_components.li, {
        children: [_jsx(_components.code, {
          children: "422 Unprocesable entity"
        }), " Could be used when there was a validation error while creating an object.\nA more complete list of status codes can be found in ", _jsx(_components.a, {
          href: "http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html",
          children: "RFC2616"
        }), "."]
      }), "\n"]
    }), "\n", _jsx(_components.h2, {
      children: "Further Reading"
    }), "\n", _jsxs(_components.ul, {
      children: ["\n", _jsx(_components.li, {
        children: _jsx(_components.a, {
          href: "https://pages.apigee.com/rs/apigee/images/api-design-ebook-2012-03.pdf",
          children: "API Design Ebook"
        })
      }), "\n", _jsx(_components.li, {
        children: _jsx(_components.a, {
          href: "http://www.vinaysahni.com/best-practices-for-a-pragmatic-restful-api",
          children: "Best Practices for a Pragmatic RESTful API"
        })
      }), "\n"]
    })]
  });
}
function MDXContent(props = {}) {
  const {wrapper: MDXLayout} = props.components || ({});
  return MDXLayout ? _jsx(MDXLayout, Object.assign({}, props, {
    children: _jsx(_createMdxContent, props)
  })) : _createMdxContent(props);
}
return {
  default: MDXContent
};


<p>This post was originally on a blog I started for creating web applications. This post goes into RESTful interfaces and how to design them.</p>
<p>RESTful APIs are a common way for applications to be able to communicate with each other.  An important part about RESTful APIs is that they are <em>consistent</em>.  Naming, verbage, actions, and errors should be consistent within your API and with how other APIs behave.</p>
<p>Here are some tips and questions that you should ask yourself when developing an API.</p>
<h2>Are you using PUT and POST correctly?</h2>
<p>Both PUT and POST can be used for creating. You do not need to support both PUT and POST. Consider the following design decisions:</p>
<ul>
<li>Do you name your URL objects you create explicitly, or let the server decide? If you name them then use PUT. If you let the server decide then use POST.</li>
<li>PUT is idempotent, so if you PUT an object twice, it has no effect. This is a nice property, so I would use PUT when possible.</li>
<li>You can update or create a resource with PUT with the same object URL</li>
<li>With POST you can have 2 requests coming in at the same time making modifications to a URL, and they may update different parts of the object.</li>
</ul>
<p>See <a href="http://stackoverflow.com/questions/630453/put-vs-post-in-rest">this StackOverflow question for more information</a>.</p>
<h2>Are you using appropriate verbs?</h2>
<p>When making a REST API, your verbs are your request types, not actual verbs in your URL!  Your URLs should use nouns, not verbs!  Remember to use the plural form for multiple results.</p>
<p>Use your URLs to specify your objects.  Here are some examples of RESTful style requests:</p>
<p><strong>Obtain 1 Question</strong></p>
<div class="overflow-auto rounded bg-gray-200 p-4 font-mono text-sm dark:bg-gray-800 dark:text-gray-100"><pre><code>GET /questions/&lt;question&gt;
</code></pre></div>
<p><strong>Obtain All Questions</strong></p>
<div class="overflow-auto rounded bg-gray-200 p-4 font-mono text-sm dark:bg-gray-800 dark:text-gray-100"><pre><code>GET /questions
</code></pre></div>
<p><strong>Append/Update Question</strong></p>
<div class="overflow-auto rounded bg-gray-200 p-4 font-mono text-sm dark:bg-gray-800 dark:text-gray-100"><pre><code>POST /questions/&lt;existing_question&gt;
</code></pre></div>
<p><strong>Create a New Question</strong></p>
<div class="overflow-auto rounded bg-gray-200 p-4 font-mono text-sm dark:bg-gray-800 dark:text-gray-100"><pre><code>PUT /questions/&lt;new_question&gt;
</code></pre></div>
<p><strong>Overwrite a Question</strong></p>
<div class="overflow-auto rounded bg-gray-200 p-4 font-mono text-sm dark:bg-gray-800 dark:text-gray-100"><pre><code>PUT /questions/&lt;existing_question&gt;
</code></pre></div>
<p><strong>Delete Question</strong></p>
<div class="overflow-auto rounded bg-gray-200 p-4 font-mono text-sm dark:bg-gray-800 dark:text-gray-100"><pre><code>DELETE /questions/&lt;existing_question&gt;
</code></pre></div>
<h2>Nested Resources should be exenstions, not entirely different queries</h2>
<p>If you want to get answers to a question, using the above examples as a starting point, the URL should be:</p>
<div class="overflow-auto rounded bg-gray-200 p-4 font-mono text-sm dark:bg-gray-800 dark:text-gray-100"><pre><code>GET /questions/1/answers
</code></pre></div>
<p>This is nested routing and it helps for a cleaner design.</p>
<h2>Do you have a plan to version your API?</h2>
<p>There are different ways to version your API, but it&#x27;s nice to plan ahead in order for consumers of your API to be prepared.</p>
<p><a href="https://developer.github.com/v3/media/#request-specific-version">Github uses</a> the <code>Accept</code> HTTP header to pass the desired version to the API.</p>
<p>Another less common method is to version the application in the URL: <code>/api/v1/...</code>.</p>
<h2>Paging</h2>
<p>Large result sets should be paginated, you can use <a href="https://developer.github.com/guides/traversing-with-pagination/">the Github method</a> for indicated next and previous pages of results using the <code>Link</code> HTTP header.</p>
<h2>HTTP Status Codes</h2>
<p><a href="https://bourgeois.me/rest/">This list of HTTP Status codes</a> and their meaning is very helpful for knowing what HTTP Status your API should be returning.  It has been duplicated here as a backup:</p>
<h3>Success codes</h3>
<ul>
<li><code>201 Created</code> should be used when creating content (INSERT)</li>
<li><code>202 Accepted</code> should be used when a request is queued for background processing (async tasks),</li>
<li><code>204 No Content</code> should be used when the request was properly executed but no content was returned (a good example would be when you delete something).</li>
</ul>
<h3>Client error codes</h3>
<ul>
<li><code>400 Bad Request</code> should be used when there was an error while processing the request payload (malformed JSON, for instance).</li>
<li><code>401 Unauthorized</code> should be used when a request is not authenticiated (wrong access token, or username or password).</li>
<li><code>403 Forbidden</code> should be used when the request is successfully authenticiated (see 401), but the action was forbidden.</li>
<li><code>406 Not Acceptable</code> should be used when the requested format is not available (for instance, when requesting an XML resource from a JSON only server).</li>
<li><code>410 Gone Should</code> be returned when the requested resource is permenantely deleted and will never be available again.</li>
<li><code>422 Unprocesable entity</code> Could be used when there was a validation error while creating an object.
A more complete list of status codes can be found in <a href="http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html">RFC2616</a>.</li>
</ul>
<h2>Further Reading</h2>
<ul>
<li><a href="https://pages.apigee.com/rs/apigee/images/api-design-ebook-2012-03.pdf">API Design Ebook</a></li>
<li><a href="http://www.vinaysahni.com/best-practices-for-a-pragmatic-restful-api">Best Practices for a Pragmatic RESTful API</a></li>
</ul>


This post was originally on a blog I started for creating web applications. This post goes into RESTful interfaces and how to design them.

RESTful APIs are a common way for applications to be able to communicate with each other.  An important part about RESTful APIs is that they are *consistent*.  Naming, verbage, actions, and errors should be consistent within your API and with how other APIs behave.

Here are some tips and questions that you should ask yourself when developing an API.

## Are you using PUT and POST correctly?

Both PUT and POST can be used for creating. You do not need to support both PUT and POST. Consider the following design decisions:

- Do you name your URL objects you create explicitly, or let the server decide? If you name them then use PUT. If you let the server decide then use POST.
- PUT is idempotent, so if you PUT an object twice, it has no effect. This is a nice property, so I would use PUT when possible.
- You can update or create a resource with PUT with the same object URL
- With POST you can have 2 requests coming in at the same time making modifications to a URL, and they may update different parts of the object.

See [this StackOverflow question for more information](http://stackoverflow.com/questions/630453/put-vs-post-in-rest).

## Are you using appropriate verbs?

When making a REST API, your verbs are your request types, not actual verbs in your URL!  Your URLs should use nouns, not verbs!  Remember to use the plural form for multiple results.

Use your URLs to specify your objects.  Here are some examples of RESTful style requests:

**Obtain 1 Question**

```
GET /questions/<question>
```

**Obtain All Questions**

```
GET /questions
```

**Append/Update Question**

```
POST /questions/<existing_question>
```

**Create a New Question**

```
PUT /questions/<new_question>
```

**Overwrite a Question**

```
PUT /questions/<existing_question>
```

**Delete Question**

```
DELETE /questions/<existing_question>
```

## Nested Resources should be exenstions, not entirely different queries

If you want to get answers to a question, using the above examples as a starting point, the URL should be:

```
GET /questions/1/answers
```

This is nested routing and it helps for a cleaner design.

## Do you have a plan to version your API?

There are different ways to version your API, but it's nice to plan ahead in order for consumers of your API to be prepared.

[Github uses](https://developer.github.com/v3/media/#request-specific-version) the `Accept` HTTP header to pass the desired version to the API.

Another less common method is to version the application in the URL: `/api/v1/...`.

## Paging

Large result sets should be paginated, you can use [the Github method](https://developer.github.com/guides/traversing-with-pagination/) for indicated next and previous pages of results using the `Link` HTTP header.

## HTTP Status Codes

[This list of HTTP Status codes](https://bourgeois.me/rest/) and their meaning is very helpful for knowing what HTTP Status your API should be returning.  It has been duplicated here as a backup:

### Success codes

- `201 Created` should be used when creating content (INSERT)
- `202 Accepted` should be used when a request is queued for background processing (async tasks),
- `204 No Content` should be used when the request was properly executed but no content was returned (a good example would be when you delete something).

### Client error codes

- `400 Bad Request` should be used when there was an error while processing the request payload (malformed JSON, for instance).
- `401 Unauthorized` should be used when a request is not authenticiated (wrong access token, or username or password).
- `403 Forbidden` should be used when the request is successfully authenticiated (see 401), but the action was forbidden.
- `406 Not Acceptable` should be used when the requested format is not available (for instance, when requesting an XML resource from a JSON only server).
- `410 Gone Should` be returned when the requested resource is permenantely deleted and will never be available again.
- `422 Unprocesable entity` Could be used when there was a validation error while creating an object.
A more complete list of status codes can be found in [RFC2616](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html).

## Further Reading

- [API Design Ebook](https://pages.apigee.com/rs/apigee/images/api-design-ebook-2012-03.pdf)
- [Best Practices for a Pragmatic RESTful API](http://www.vinaysahni.com/best-practices-for-a-pragmatic-restful-api)


RESTful Interfaces