Resource management scenarios

The resource management scenarios discussed in this document have been separated based on the type of issue being faced:

Each section contains a decision tree to aid the selection of the appropriate HTTP status and message for different resource management situations.

Removing a resource

When a resource has been removed or deleted (permanently unavailable) or it is only temporarily unavailable, it is important to avoid presenting the user with the File not found (404) status.

In a perfectly maintained architecture the File not found (404) status would only be required when the user enters an URL that never existed (example: due to an input error, or a failed URL guess), and even then, you may be able to provide a more helpful response (see Handling errors section for more discussion).

Decision tree:

  • Is the resource being removed permanently? (See RMS 1.1)
  • Is the resource being removed only temporarily? (See RMS 1.2)
  • Is the future existence of the removed resource uncertain? (For example: The resource had to be removed, but it has not yet been decided whether it will be re-published) (See RMS 1.3)

Moving a resource

HTTP redirection is useful as a fallback measure for when a URL can no longer be persisted because the resource has been relocated.

Decision tree:

  • Is a single file being moved to a single destination?
  • Are a single file's contents being split among multiple destinations? (See RMS 2.3)
  • Are multiple files' contents being joined into a single destination?

Aliasing a resource

It can sometimes be useful to provide more than one URL that references the same resource, this is referred to as URL aliasing. It is important to remember that for every resource there should be only one canonical URL, any aliases for the same resource should redirect to the canonical URL.

Decision tree:

  • Is the address a promotional address for a resource? (See RMS 2.6)
  • Is the alias otherwise an alternate address for a resource? (See RMS 2.6)

Processing form submissions

Best practice for handling form submissions dictate that:

  • The user should be able to return to the page containing the form they submitted using only a single click of their browser software's back button.
    • When a user is returned to the form page, the form should still contain the data the user submitted (modern user-agents provide this behaviour by default).
  • If the action is 'safe', the resultant page should be directly addressable (so the result page's URL can be emailed or bookmarked).

The following decision tree and the linked scenarios (including HTTP statuses and status messages) will help achieve these best practice requirements.

Decision tree:

Handling errors

When not due to user error, these conditions largely represent a breakdown in the normal operation of a production server.

In the case of user error, the nature of the problem should be relayed to the user in as much detail as necessary for the user to understand what has happened and what they can do to fix the problem.

Sometimes a user input error condition can be predicted and an alternate course of action can be suggested. For example: if the user enters a common typographical error or misspelling, a link to the correct URL can be provided to the user (auto-correction of these typographical errors through redirection is not recommended, instead see RMS 4.9).

In the case of internal server errors, it is often useful to email or otherwise alert the site's administration team when they occur and inform the user that they have been notified.

The following decision tree is not exhaustive of all potential error conditions but should be considered a good summary of common error scenarios.

Decision tree:

  • Has an error occurred with a database, validity of source XML, or other server-side error prevented the resource from being presented? (see RMS 4.1)
  • Does the requested resource exist?
    • Are the user's Accept header requirements unable to be met? (see RMS 4.2)
    • Is the user forbidden to access the resource?
      • Do you want the user to know that a resource exists at that location? (see RMS 4.3)
      • Do you want the user to not know that a resource exists at that location? (see RMS 4.4)
    • Is the server overloaded? (see RMS 4.5)
    • Is the server undergoing maintenance? (see RMS 4.6)
  • Did the resource ever exist?
  • Is it certain that the requested resource never existed?
    • Did the user input a known common typographical error? (see RMS 4.7)
    • Does no resource exist for the requested URL? (see RMS 4.8)
  • Is it uncertain whether a resource ever existed at the requested URL? (see RMS 4.9)

Using best fit statuses

It is important to use the most appropriate (best fit) status for each scenario. Once all previous decision trees have been considered, the following should also be considered before using 200, 302 or 404 statuses.

Decision tree:

  • Restricting access to authorised users? (see RMS 5.1)
  • Content negotiation between translated versions of a resource? (see RMS 5.2)