"use strict";
const {Fragment: _Fragment, jsx: _jsx, jsxs: _jsxs} = arguments[0];
function _createMdxContent(props) {
  const _components = {
    a: "a",
    code: "code",
    em: "em",
    h2: "h2",
    li: "li",
    p: "p",
    ul: "ul",
    ...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 performance of web applications."
    }), "\n", _jsx(_components.h2, {
      children: "Cache Pages"
    }), "\n", _jsxs(_components.p, {
      children: ["Dynamic pages should be cached in order to improve performance.  Understand how ", _jsx(_components.a, {
        href: "https://www.mnot.net/cache_docs/",
        children: "Web Caching"
      }), " works."]
    }), "\n", _jsx(_components.h2, {
      children: "Use Cache Manifest for Offline Performance"
    }), "\n", _jsxs(_components.p, {
      children: ["If you would like your page to be accessible offline after a user has already visited it, look into the ", _jsx(_components.a, {
        href: "http://www.w3.org/TR/2011/WD-html5-20110525/offline.html",
        children: "Cache Manifest"
      }), "."]
    }), "\n", _jsx(_components.h2, {
      children: "Optimize Images"
    }), "\n", _jsx(_components.p, {
      children: "Compress and crop images for best performance."
    }), "\n", _jsx(_components.h2, {
      children: "Gzip Content"
    }), "\n", _jsxs(_components.p, {
      children: ["Most web servers can be configured to automatically do this for you.  Look into ", _jsx(_components.a, {
        href: "https://developer.yahoo.com/performance/rules.html#gzip",
        children: "Yahoo's Developer Network discussion"
      }), " for more information."]
    }), "\n", _jsx(_components.h2, {
      children: "Concatenate Stylesheets and Script Files"
    }), "\n", _jsxs(_components.p, {
      children: ["Before deploying to production, concatenate Stylesheets and Script files to reduce the number of brwoser connections and improve gzip compression.  There are many solutions to concatinating and compressing CSS and JavaScript files.  You can look into ", _jsx(_components.a, {
        href: "http://gruntjs.com/",
        children: "Grunt"
      }), " for a Node.js solution."]
    }), "\n", _jsx(_components.h2, {
      children: "Use CSS Image Sprites When Possible"
    }), "\n", _jsxs(_components.p, {
      children: ["Use ", _jsx(_components.a, {
        href: "http://alistapart.com/article/sprites",
        children: "CSS Image Sprites"
      }), " when possible for small related images like toolbars.  The helps minimize HTTP requess and improves gzip compression."]
    }), "\n", _jsx(_components.h2, {
      children: "Split Static Content to Its Own Domain"
    }), "\n", _jsxs(_components.p, {
      children: ["Static content like images, CSS, JavaScript, and other content should go in a separate domain that ", _jsx(_components.em, {
        children: "does not use cookies"
      }), ".  Cookies are sent with every request to the domain and all of its subdomains.  Use a Content Delivery Network (CDN) if possible."]
    }), "\n", _jsx(_components.h2, {
      children: "Minify JavasScript"
    }), "\n", _jsxs(_components.p, {
      children: ["Minify your JavaScript if possible.  Use the ", _jsx(_components.a, {
        href: "https://developers.google.com/closure/compiler/",
        children: "Google Closure Compiler"
      }), " or look into ", _jsx(_components.a, {
        href: "http://stackoverflow.com/questions/6539837/concat-and-minify-js-files-in-node",
        children: "this Stackoverflow question for concatenating and minifying JavaScript files in Node"
      }), "."]
    }), "\n", _jsx(_components.h2, {
      children: "Make a Favicon.ico File"
    }), "\n", _jsxs(_components.p, {
      children: ["Make sure there’s a ", _jsx(_components.code, {
        children: "favicon.ico"
      }), " file in the root of the site, i.e. ", _jsx(_components.code, {
        children: "/favicon.ico"
      }), ". ", _jsx(_components.a, {
        href: "https://mathiasbynens.be/notes/rel-shortcut-icon",
        children: "Browsers will automatically request it"
      }), ", even if the icon isn’t mentioned in the HTML at all. If you don’t have a ", _jsx(_components.code, {
        children: "/favicon.ico"
      }), ", this will result in a lot of 404s, draining your server’s bandwidth."]
    }), "\n", _jsxs(_components.p, {
      children: ["Check your Favicon against ", _jsx(_components.a, {
        href: "http://realfavicongenerator.net/",
        children: "The Real Favicon Generator"
      }), ".  It takes care of favicons for:"]
    }), "\n", _jsxs(_components.ul, {
      children: ["\n", _jsx(_components.li, {
        children: "Desktop Browsers"
      }), "\n", _jsx(_components.li, {
        children: "iOS Home Screen (Favorite icons)"
      }), "\n", _jsx(_components.li, {
        children: "Android Home Screen (Favorite icons)"
      }), "\n", _jsx(_components.li, {
        children: "Windows 8 Tile (Favorite tiles)"
      }), "\n", _jsx(_components.li, {
        children: "Windows Task Bar (App style icon)"
      }), "\n"]
    }), "\n", _jsx(_components.p, {
      children: "It also helps you compress the icons and generates the HTML markup for you."
    })]
  });
}
function MDXContent(props = {}) {
  const {wrapper: MDXLayout} = props.components || ({});
  return MDXLayout ? _jsx(MDXLayout, {
    ...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 performance of web applications.</p>
<h2>Cache Pages</h2>
<p>Dynamic pages should be cached in order to improve performance.  Understand how <a href="https://www.mnot.net/cache_docs/">Web Caching</a> works.</p>
<h2>Use Cache Manifest for Offline Performance</h2>
<p>If you would like your page to be accessible offline after a user has already visited it, look into the <a href="http://www.w3.org/TR/2011/WD-html5-20110525/offline.html">Cache Manifest</a>.</p>
<h2>Optimize Images</h2>
<p>Compress and crop images for best performance.</p>
<h2>Gzip Content</h2>
<p>Most web servers can be configured to automatically do this for you.  Look into <a href="https://developer.yahoo.com/performance/rules.html#gzip">Yahoo&#x27;s Developer Network discussion</a> for more information.</p>
<h2>Concatenate Stylesheets and Script Files</h2>
<p>Before deploying to production, concatenate Stylesheets and Script files to reduce the number of brwoser connections and improve gzip compression.  There are many solutions to concatinating and compressing CSS and JavaScript files.  You can look into <a href="http://gruntjs.com/">Grunt</a> for a Node.js solution.</p>
<h2>Use CSS Image Sprites When Possible</h2>
<p>Use <a href="http://alistapart.com/article/sprites">CSS Image Sprites</a> when possible for small related images like toolbars.  The helps minimize HTTP requess and improves gzip compression.</p>
<h2>Split Static Content to Its Own Domain</h2>
<p>Static content like images, CSS, JavaScript, and other content should go in a separate domain that <em>does not use cookies</em>.  Cookies are sent with every request to the domain and all of its subdomains.  Use a Content Delivery Network (CDN) if possible.</p>
<h2>Minify JavasScript</h2>
<p>Minify your JavaScript if possible.  Use the <a href="https://developers.google.com/closure/compiler/">Google Closure Compiler</a> or look into <a href="http://stackoverflow.com/questions/6539837/concat-and-minify-js-files-in-node">this Stackoverflow question for concatenating and minifying JavaScript files in Node</a>.</p>
<h2>Make a Favicon.ico File</h2>
<p>Make sure there’s a <code>favicon.ico</code> file in the root of the site, i.e. <code>/favicon.ico</code>. <a href="https://mathiasbynens.be/notes/rel-shortcut-icon">Browsers will automatically request it</a>, even if the icon isn’t mentioned in the HTML at all. If you don’t have a <code>/favicon.ico</code>, this will result in a lot of 404s, draining your server’s bandwidth.</p>
<p>Check your Favicon against <a href="http://realfavicongenerator.net/">The Real Favicon Generator</a>.  It takes care of favicons for:</p>
<ul>
<li>Desktop Browsers</li>
<li>iOS Home Screen (Favorite icons)</li>
<li>Android Home Screen (Favorite icons)</li>
<li>Windows 8 Tile (Favorite tiles)</li>
<li>Windows Task Bar (App style icon)</li>
</ul>
<p>It also helps you compress the icons and generates the HTML markup for you.</p>


This post was originally on a blog I started for creating web applications. This post goes into performance of web applications.

## Cache Pages

Dynamic pages should be cached in order to improve performance.  Understand how [Web Caching](https://www.mnot.net/cache_docs/) works.

## Use Cache Manifest for Offline Performance

If you would like your page to be accessible offline after a user has already visited it, look into the [Cache Manifest](http://www.w3.org/TR/2011/WD-html5-20110525/offline.html).

## Optimize Images

Compress and crop images for best performance.

## Gzip Content

Most web servers can be configured to automatically do this for you.  Look into [Yahoo's Developer Network discussion](https://developer.yahoo.com/performance/rules.html#gzip) for more information.

## Concatenate Stylesheets and Script Files

Before deploying to production, concatenate Stylesheets and Script files to reduce the number of brwoser connections and improve gzip compression.  There are many solutions to concatinating and compressing CSS and JavaScript files.  You can look into [Grunt](http://gruntjs.com/) for a Node.js solution.

## Use CSS Image Sprites When Possible

Use [CSS Image Sprites](http://alistapart.com/article/sprites) when possible for small related images like toolbars.  The helps minimize HTTP requess and improves gzip compression.

## Split Static Content to Its Own Domain

Static content like images, CSS, JavaScript, and other content should go in a separate domain that *does not use cookies*.  Cookies are sent with every request to the domain and all of its subdomains.  Use a Content Delivery Network (CDN) if possible.

## Minify JavasScript

Minify your JavaScript if possible.  Use the [Google Closure Compiler](https://developers.google.com/closure/compiler/) or look into [this Stackoverflow question for concatenating and minifying JavaScript files in Node](http://stackoverflow.com/questions/6539837/concat-and-minify-js-files-in-node).

## Make a Favicon.ico File

Make sure there’s a `favicon.ico` file in the root of the site, i.e. `/favicon.ico`. [Browsers will automatically request it](https://mathiasbynens.be/notes/rel-shortcut-icon), even if the icon isn’t mentioned in the HTML at all. If you don’t have a `/favicon.ico`, this will result in a lot of 404s, draining your server’s bandwidth.

Check your Favicon against [The Real Favicon Generator](http://realfavicongenerator.net/).  It takes care of favicons for:

* Desktop Browsers
* iOS Home Screen (Favorite icons)
* Android Home Screen (Favorite icons)
* Windows 8 Tile (Favorite tiles)
* Windows Task Bar (App style icon)

It also helps you compress the icons and generates the HTML markup for you.


Performance

"use strict";
const {Fragment: _Fragment, jsx: _jsx, jsxs: _jsxs} = arguments[0];
function _createMdxContent(props) {
  const _components = {
    h2: "h2",
    p: "p",
    ...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 maintenance of web applications."
    }), "\n", _jsx(_components.h2, {
      children: "Setup an Error/Bug Reporting Solution"
    }), "\n", _jsx(_components.p, {
      children: "Use Github's issue tracker, or JIRA, or anything.  Keeping track of issues, enhancements, and bugs in progress helps tremendously down the line."
    }), "\n", _jsx(_components.h2, {
      children: "Setup a Contact Form"
    }), "\n", _jsx(_components.p, {
      children: "Simple email forms or using other services like Reddit or even forums can help users give you suggestions and criticism."
    }), "\n", _jsx(_components.h2, {
      children: "Documentation"
    }), "\n", _jsx(_components.p, {
      children: "Document how the application works, the deployment progress, and anything else you can!  Those who do future maintenance will thank you."
    }), "\n", _jsx(_components.h2, {
      children: "Backup/Restore Strategy"
    }), "\n", _jsx(_components.p, {
      children: "Have a backup strategy and a restore strategy."
    }), "\n", _jsx(_components.h2, {
      children: "Version Control Your Project"
    }), "\n", _jsx(_components.p, {
      children: "Use Subversion, Mecurial, Git to version control your files.  Preferably Git ;) ."
    }), "\n", _jsx(_components.h2, {
      children: "Setup Unit Tests/Acceptance Tests/Regression Test etc"
    }), "\n", _jsx(_components.p, {
      children: "Getting any type of tests is very useful, especially acceptance testing and integration testing."
    }), "\n", _jsx(_components.h2, {
      children: "Setup Logging"
    }), "\n", _jsx(_components.p, {
      children: "Log any application errors, user errors, exceptions, etc."
    })]
  });
}
function MDXContent(props = {}) {
  const {wrapper: MDXLayout} = props.components || ({});
  return MDXLayout ? _jsx(MDXLayout, {
    ...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 maintenance of web applications.</p>
<h2>Setup an Error/Bug Reporting Solution</h2>
<p>Use Github&#x27;s issue tracker, or JIRA, or anything.  Keeping track of issues, enhancements, and bugs in progress helps tremendously down the line.</p>
<h2>Setup a Contact Form</h2>
<p>Simple email forms or using other services like Reddit or even forums can help users give you suggestions and criticism.</p>
<h2>Documentation</h2>
<p>Document how the application works, the deployment progress, and anything else you can!  Those who do future maintenance will thank you.</p>
<h2>Backup/Restore Strategy</h2>
<p>Have a backup strategy and a restore strategy.</p>
<h2>Version Control Your Project</h2>
<p>Use Subversion, Mecurial, Git to version control your files.  Preferably Git ;) .</p>
<h2>Setup Unit Tests/Acceptance Tests/Regression Test etc</h2>
<p>Getting any type of tests is very useful, especially acceptance testing and integration testing.</p>
<h2>Setup Logging</h2>
<p>Log any application errors, user errors, exceptions, etc.</p>


This post was originally on a blog I started for creating web applications. This post goes into maintenance of web applications.

## Setup an Error/Bug Reporting Solution

Use Github's issue tracker, or JIRA, or anything.  Keeping track of issues, enhancements, and bugs in progress helps tremendously down the line.

## Setup a Contact Form

Simple email forms or using other services like Reddit or even forums can help users give you suggestions and criticism.

## Documentation

Document how the application works, the deployment progress, and anything else you can!  Those who do future maintenance will thank you.

## Backup/Restore Strategy

Have a backup strategy and a restore strategy.

## Version Control Your Project

Use Subversion, Mecurial, Git to version control your files.  Preferably Git ;) .

## Setup Unit Tests/Acceptance Tests/Regression Test etc

Getting any type of tests is very useful, especially acceptance testing and integration testing.

## Setup Logging

Log any application errors, user errors, exceptions, etc.


Maintenance

"use strict";
const {Fragment: _Fragment, jsx: _jsx, jsxs: _jsxs} = arguments[0];
function _createMdxContent(props) {
  const _components = {
    a: "a",
    code: "code",
    em: "em",
    h2: "h2",
    h3: "h3",
    li: "li",
    p: "p",
    pre: "pre",
    strong: "strong",
    ul: "ul",
    ...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, {
    ...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-2xl bg-[#0e005d6d] p-4 font-mono text-sm dark:bg-[#0e005d6d] 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-2xl bg-[#0e005d6d] p-4 font-mono text-sm dark:bg-[#0e005d6d] dark:text-gray-100"><pre><code>GET /questions
</code></pre></div>
<p><strong>Append/Update Question</strong></p>
<div class="overflow-auto rounded-2xl bg-[#0e005d6d] p-4 font-mono text-sm dark:bg-[#0e005d6d] 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-2xl bg-[#0e005d6d] p-4 font-mono text-sm dark:bg-[#0e005d6d] 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-2xl bg-[#0e005d6d] p-4 font-mono text-sm dark:bg-[#0e005d6d] 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-2xl bg-[#0e005d6d] p-4 font-mono text-sm dark:bg-[#0e005d6d] 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-2xl bg-[#0e005d6d] p-4 font-mono text-sm dark:bg-[#0e005d6d] 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)


Blog Page 5

Performance

Maintenance

RESTful Interfaces