I found the standard REST API best practices to be very confusing, because you need to know all the HTTP methods such as GET/POST/PUT/DELETE/PATCH etc. Not only that, while calling an API, you might need to provide the following:

  1. Body
  2. Params
  3. Querystring
  4. Headers

In my opinion, this is not only confusing for the server developer, it also confusing for the client.

Therefore, I wanted to know are there any specific reasons to have a variety of methods instead of having one unified way? Is it for security measure?

I will be glad if you could provide some material reference from IETF RFC or even ISO documents rather than your personal opinion.

  • 1
    The only reason is a vocabulary shared between participants. It makes development of new clients and servers easier to document and develop. – Basilevs Nov 15 '18 at 3:35
  • 1
    are there any specific reasons to have a variety of methods instead of having one unified way? -- There is one unified way; it's called REST. The implementation details you are referring to are just that: implementation details. There are numerous libraries out there that clients can use that don't require any knowledge of these implementation details. See here for an example. – Robert Harvey Nov 15 '18 at 15:57
  • Can I know why is this question downvoted? – Wong Jia Hau Nov 16 '18 at 1:32
  • 1
    I didn't downvote your question, but if I had to guess, it would be because your question is based on faulty assumptions and is primarily opinion-based. – Robert Harvey Nov 18 '18 at 23:09

Therefore, I wanted to know are there any specific reasons to have a variety of methods instead of having one unified way? Is it for security measure?

No, it's not for security.

The reason for the variation in standard methods is that we can now use generic components that understand those semantics to do a lot of the work for us.

For example, using the standard REST methods the standard way means that cache invalidation can be handled automatically, by generic components. It means that generic components can know which requests to resend when the response is lost on an unreliable network, and which cannot.

I will be glad if you could provide some material reference from IETF RFC or even ISO documents rather than your personal opinion.

You should start with Fielding's thesis, in particular Chapter 6, where he reviews the "experience and lessons learned from applying REST" to "guide the design and development of the architecture for the modern Web".

Jim Webber's talk Domain-Driven Design for RESTful Systems is another good take, especially the foundation material in the early part of the talk.

  • 1
    There are security implications of using HTTP verbs incorrectly. The main one is using GET for anything other than 'safe' operations is a really insecure thing to do that can create vulnerable APIs. – JimmyJames Nov 15 '18 at 15:45

REST, and REST implemented by HTTP aren't the same thing.

A Restful service is simply a service that completes an interaction in a single request/response pair.

A Restful server does not maintain a session or any active state information after completing the request/response. To create the illusion of a session, each request contains all identifying information, an operation - usually CRUD based (but not necessarily), and all required extra data. If any part of the request is omitted, the server does not query for it, or maintain a session to wait for it. It responds with an error, possibly identifying why, and then closes the connection. Otherwise the server processes the request, returns a response, and then forgets all the details about the request/response pair. The next request will have to submit complete details, even if many are identical to the previous request.

This has many benefits from development, and maintenance perspectives. It keeps the interaction simple, the system modular, and creates strong boundaries which makes testing (and unit testing) much easier and quicker. The simplification of the state also makes horizontal scaling in production much easier.

REST by HTTP leverages the HTTP protocol to provide a CRUD orientated Restful interface. Many of the issues around connection (tcp/ip), security (ssl), authentication (oauth), service naming (domain names, url paths), libraries for parsing/generating http request/response messages, etc.. have solutions that are mature and well tested.

As you've already noticed HTTP is almost but not quite a restful protocol. Also because of its age, it has accumulated numerous features that don't always sit well, or have alternate solutions. This sure does lead to confusion. Its not really anything todo with security specifically, but the fact that the Web is an open platform. Many providers did not (and still don't) provide full support for all standards, this lead to many "defacto"/"lowest common denominator" elements becoming the norm, and themselves becoming documented in later standard amendments.

As for good practices, draw from standard software interface design. It is just expressed in terms of a HTTP request/response. Alternately research other products offering a Restful interface and study how they are designed. Unless you have a wholly novel application, there is likely a similar product out there already. Learn from them.

In my opinion focus less on the fact you are using HTTP, focus more on being Restful. The business logic behind your service should not care if the request originated from HTTP, an email, a desktop application, or some other I/O device.

To this end:

  • Identify the nouns in your system and what you can do directly with them.
    • Read operations
    • Execute operations
    • Update operations
    • Delete operations
    • Create operations.
  • Each object has a unique name
    • Each operation on that object has a unique name.
    • The operation's request sensibly holds all the information needed to complete the operation.
    • The operation's response sensibly holds all the information that the operation could complete with
      • including error details like "Not Authorised" or "Something unexpected happened, the request failed"
      • don't reveal implementation details such as stack traces, or exception names, send those to the server's log instead.

Now grab the HTTP Rest guides and translate your Restful services request/responses to be sent via HTTP.

  • GET URL -> readonly operation against that object
  • DELETE URL -> delete operation against that object
  • POST URL/{id}/up/item/{name}/check?key=val { "country":"au" } -> an action with side-effects against something of this name that's here under that id, with some key value, and a country is important to the operation somehow.
  • ...

If the request needs parameters, find header fields, parameters, body, and querystring that provide the desired outcome. There is no right answer here, its all contextual based on what is desired. eg:

  • Query parameters can be bookmarked because they are part of the URL.
  • a JSON body provides easy serialisation/deserialisation to most data structures.

It is perfectly acceptable to accept http request where some of the data is in the URL, some in the Query string, and some in the Body. Just as long as its clearly documented as to how, when, and the expected behaviour.

The important part is that all the information required to complete the request can be extracted from the HTTP request into a data structure to pass to your own business logic, and that the response can similarly be encoded in the HTTP response. That way your business logic is separate, and testable.

Now document the mapping and tell the clients of your service. They'll map from their software to this interface, and back again.

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.