Search code examples
restapi-design

REST API URL structure when resource not in URL

We are creating a two REST APIs

  1. To do a template processing
  2. To convert the HTML to PDF.

The template in 1, and the HTML in 2 can be provided along with the request body as well as present in a persistent location.

What is the best way to design the REST contract? Are these good ways to design it? Or are there better suggestions for this?

For Scenario 1

  1. PUT - /template/process; include the Template markup in the body
  2. PUT - /templates/{id}/process; there is a template with that {id} in a persistent location

For Scenario 2

  1. PUT /html2pdf/convert with the HTML markup mentioned in the body
  2. PUT html2pdf/{id}/convert with the resource HTML with the {id} available in a persistent location.

Is it a good idea to have the action too (process, convert in this case) in the URL? Or is it possible to give a meaning to it using the HTTP verb itself?

Solution

  • The use of PUT is suspicious. Remember, part of the point of REST is that we have a uniform interface - everybody understands HTTP messages the same way.

    In particular, PUT is the method token that we use if we are uploading a web page to a server. The semantics of the request are analogous to "save" or "upsert" - you are telling the server that you want to make the server's copy of the target resource look like your copy of the target resource.

    POST serves many useful purposes in HTTP, including the general purpose of “this action isn’t worth standardizing.” -- Fielding, 2009

    What we want in a lot of cases similar to yours is an effectively read only request with a payload. As of early 2021, the registry of HTTP methods doesn't have a good match for that case - the closest options are SEARCH and REPORT, but both of those carry WebDAV baggage.

    But in late 2020, the HTTP WG adopted the draft-snell-search-method spec:

    the scope of work is to define a method that has the behavior of a GET with a body -- Tommy Pauly

    So when that work is done, we'll have another standard method to consider for this type of problem.

    Is it a good idea to have the action too in the URL?

    It's a neutral idea.

    URL/URI are identifiers; they are (from the point of view of the protocol) semantically opaque. So long as your spelling conventions are consistent with the production rules defined in RFC 3986, you can do as you like.

    Any HTTP compliant component should understand that the semantics of the message are defined my the method token, not by the target-uri.

    Resources are generalization of documents. The URI is, effectively, the "name" of the document. You can use any name for your documents that makes sense to your human beings (operators looking at access logs, tech writers trying to document your app, other developers trying to read those documents, etc).