Which HTTP Method to Choose When Building Restful API

Question

I am new to node.js and have my first node.js Restful API built in hapi.js framework. All the services do is basically doing database query. An example of the services is like this:

let myservice = {
    method: "POST",
    path: "/updateRule",
    config: {
        handler: (request, reply) => {
            updateRule(request.payload)
            .then((result) => {
                reply(successResponse(request, result));
            })
            .catch((err) => reply(failResponse(request, err)).code(500));
        },
        validate: {
            payload: {
                ruleId: joi.number().required(),
                ruleName: joi.string().required(),
                ruleDesc: joi.string().required()
            }
        },
        auth: "jwt",
        tags: ["api", "a3i"]
    },
}

updateRule(input): Promise<any> {
        return new Promise((resolve, reject) => {
            let query = `select a3i.update_rule(p_rul_id := ${input.ruleId}, p_rul_name := '${input.ruleName}', p_rul_desc := '${input.ruleDesc}')`;
            postgresQuery(lbPostgres, query, (data, commit, rollback) => {
                try {
                    let count = data.rows[0].update_rule.count;
                    if (count === 1) {
                        let ruleId = data.rows[0].update_rule.result[0];
                        let payload: SuccessPayload = {
                            type: "string",
                            content: `Rule ${ruleId} has been updated`
                        };
                        commit();
                        resolve(payload);
                    } else {
                        let thisErr = new Error("No rule can be found.");
                        thisErr.name = "4003";
                        throw thisErr;
                    }
                }
                catch (err) {
                    rollback();
                    if (err.name === "4003") {
                        reject(detailError(4003, err.message));
                    } else {
                        reject(detailError(4001, err.message));
                    }
                }
            }, reject);
        });
    }

As you can see, when the service is called, it evokes a database call (query) and updates specified row in database table. Similarly, I have other services named createRule/deleteRule creating/deleting records in database table. In my opinion, the difference between the services is doing different database query. I read this post PUT vs. POST in REST but couldn't see any difference of POST and PUT in my case.

Here are my questions:

1. What HTTP method should I used in this case?

2. Most of Restful API examples (for example https://www.codementor.io/olatundegaruba/nodejs-restful-apis-in-10-minutes-q0sgsfhbd) use the same URL with different HTTP methods to do different operations on same "resource", which in my opinion is usually a database table. What's the benefit of this architecture compared with my practice in which one URL only has one HTTP method and only do one type of operation?

I know this question does not refer to a problem and is not specific. Some people may give it a down-vote. But as a beginner I really want to know what's a typical Restful API and make sure my API is "best practice". Please help!

Answer 1

If the resource already exists and thus you have a specific URI to that exact resource and you want to update it, then use PUT.

If the resource does not exist yet and you want to create it and you will let the server pick the URI that represents that new resource, then use POST and the POST URI will be a generic "create new resource" URI, not a URI to a specific resource and it will create the URI that represents that resource.

You can also use PUT to create a new resource if the caller is going to create the resource URI that represents the new resource. In that case, you would just PUT to that new resource and, if a resource with that URI already exists, it would be updated, if not, it would be created.

You do not have to support both. You can decide to make your api work in a way that you just use one or the other.

---

In your specific case, an update of a specific row in your database that already exists would pretty much always be a PUT because it already exists so you're doing a PUT to a specific URI that represents that row.

What's the benefit of this architecture compared with my practice in which one URL only has one HTTP method and only do one type of operation?

It's really up to you how you want to present your API. The general concept behind REST is that you have several components:

resource identifier
data
method

In some cases, the method can be subsumed by GET, PUT, POST or DELETE so you just need the resource identifier, data and GET, PUT, POST or DELETE.

In other cases or other designs, the method is more detailed than can be expressed in just a PUT or POST, so you have a method actually in the URL in which case, you may not need the distinction between PUT and POST as much.

For example, an action might be "buy". While you could capture that in a POST where the method is implied by the rest of the URL, you may want to actually POST to a URL that has a method in it: /buy for clarity and then you may use that same endpoint prefix with other methods such as /addToCart, etc... It really depends upon what the objects are in your REST design and what operations you want to surface on them. Sometimes, the objects lends themselves to just GET, PUT, POST and DELETE and sometimes, you want more info in the URL as to the specific operation to be carried out on that resource.

Answer 2

If you want to be Rest compliant, you can just use Post and Get. If you want to be Restfull, you need to base your method on the CRUD

• Create -> Post
• Read -> Get
• Update -> Put or Patch
• Delete -> Delete

About building a full API, using method on the same URL could be easier to build / understand. All queries about your user will be on the user url and not user/get, user/add, user/update ... It let you have the same functionality, without too much different URL.

When you build an API, you will want to have some logs, for stats analysis and other stuff. This way, if you split with your method, you can just have a filter to logs how many Post requests, or Get requests.

In fact, you could build an API only with Get requests too. But spliting with methods and URL is the best way to avoid complexes URL (or URL with too much action name) and to have an easiest way to log every requests going through your API

- List item

• Level 1 is Rest

• Level 2 is Restfull

• Level 3 is Hateoas

You should find more informations inside some books or articles written by Martin Fowler

Answer 3

What I usually do is use "POST" for creating a new resource, and use "PUT" for updating an already existing resource.

For your second question, yes most API's use the same URL to do different things on the same resource. That could be because of security where you don't want to expose what you are doing in your URL's (/delete for example). Also, many frameworks generate an auto URL for a resource (Object Class), that is then differentiated on the request method. People just don't tend to use custom URL's for those.