Avoiding verbs in URLs in Rest API

Introduction

URLs should describe things, not actions. This makes them easier to understand and use.

When designing web APIs for managing resources like users or products.

When you want URLs to be simple and predictable for developers.

When you want to follow common web standards for REST APIs.

When you want to separate the action from the URL and use HTTP methods instead.

When you want your API to be easier to maintain and extend.

Syntax

Rest API

/resources
/resources/{id}

Use nouns (things) in URLs, not verbs (actions).

Use HTTP methods like GET, POST, PUT, DELETE to express actions.

Examples

Use HTTP methods to perform actions on the users resource.

Rest API

GET /users
POST /users
GET /users/123
PUT /users/123
DELETE /users/123

URLs represent the orders resource and specific order by ID.

Rest API

/orders
/orders/456

Do not put verbs like get, create, or delete in URLs.

Rest API

Avoid: /getUser
Avoid: /createOrder
Avoid: /deleteProduct

Sample Program

This simple API uses URLs with nouns only. Actions are done by HTTP methods like GET and POST.

Rest API

from flask import Flask, jsonify, request

app = Flask(__name__)

users = {"1": {"name": "Alice"}, "2": {"name": "Bob"}}

@app.route('/users', methods=['GET'])
def list_users():
    return jsonify(users)

@app.route('/users/<user_id>', methods=['GET'])
def get_user(user_id):
    user = users.get(user_id)
    if user:
        return jsonify(user)
    return jsonify({"error": "User not found"}), 404

@app.route('/users', methods=['POST'])
def create_user():
    data = request.json
    new_id = str(len(users) + 1)
    users[new_id] = {"name": data.get('name', 'Unknown')}
    return jsonify({"id": new_id}), 201

if __name__ == '__main__':
    app.run(debug=True)

Important Notes

HTTP methods tell what action to do, so URLs stay clean and simple.

Using nouns in URLs helps everyone understand what the URL points to.

Keep URLs consistent and predictable for easier API use.

Summary

Use nouns, not verbs, in URLs to name resources.

Use HTTP methods (GET, POST, PUT, DELETE) to express actions.

This makes APIs easier to understand and maintain.