API Operations — GET, POST, PUT, PATCH, and DELETE

DodaTech Updated 2026-06-28 5 min read

In this tutorial, you will learn about API Operations. We cover key concepts, practical examples, and best practices to help you master this topic.

OpenAPI operations define the behavior for each HTTP method on a path, including GET (read), POST (create), PUT (replace), PATCH (partial update), and DELETE (remove) operations.

In this tutorial, you will learn the conventions and implementation patterns for each HTTP method in OpenAPI, with complete examples for CRUD operations.

What You'll Learn

You will learn how to define operations for each HTTP method, understand the conventions for request bodies and response codes per method, and implement complete CRUD patterns.

Why It Matters

Each HTTP method has specific conventions about request bodies, response codes, and idempotency. Correct method definitions ensure accurate documentation and predictable API behavior.

Real-World Use

DodaTech APIs follow strict HTTP method conventions. GET is always safe and cachable. POST creates new resources. PUT fully replaces resources. PATCH applies partial modifications. DELETE removes resources and returns 204.

flowchart LR
  A[Operations] --> B[GET: Read]
  A --> C[POST: Create]
  A --> D[PUT: Replace]
  A --> E[PATCH: Partial]
  A --> F[DELETE: Remove]
  B:::current
  classDef current fill:#f90,color:#fff,stroke:#333,stroke-width:2px

GET Operations

GET retrieves resources. It should be safe (no side effects), idempotent (repeating the request produces the same result), and cacheable. GET requests have no request body.

paths:
  /users:
    get:
      operationId: listUsers
      summary: List all users
      description: Returns a paginated list of users on the platform
      parameters:
        - name: page
          in: query
          schema:
            type: integer
            default: 1
        - name: limit
          in: query
          schema:
            type: integer
            default: 20
      responses:
        "200":
          description: Successful response with user list
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: "#/components/schemas/User"
                  pagination:
                    $ref: "#/components/schemas/Pagination"
  /users/{userId}:
    get:
      operationId: getUser
      summary: Get a user by ID
      parameters:
        - name: userId
          in: path
          required: true
          schema:
            type: integer
      responses:
        "200":
          description: User found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/User"
        "404":
          $ref: "#/components/responses/NotFound"

POST Operations

POST creates new resources. It is not idempotent: creating the same resource twice produces two resources. POST requires a request body and returns 201 Created.

paths:
  /users:
    post:
      operationId: createUser
      summary: Create a new user
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateUserRequest"
      responses:
        "201":
          description: User created successfully
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/User"
        "400":
          $ref: "#/components/responses/BadRequest"
        "409":
          $ref: "#/components/responses/Conflict"

PUT Operations

PUT fully replaces a resource. It replaces the entire resource with the request body. PUT is idempotent: the same request produces the same result every time.

paths:
  /users/{userId}:
    put:
      operationId: updateUser
      summary: Replace a user
      description: Fully replaces the user resource with the provided data
      parameters:
        - name: userId
          in: path
          required: true
          schema:
            type: integer
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/UpdateUserRequest"
      responses:
        "200":
          description: User replaced successfully
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/User"
        "404":
          $ref: "#/components/responses/NotFound"

PATCH Operations

PATCH applies partial modifications to a resource. It only changes the fields specified in the request body. PATCH may or may not be idempotent depending on the implementation.

paths:
  /users/{userId}:
    patch:
      operationId: patchUser
      summary: Update user fields
      description: Partially updates the user. Only provided fields are changed.
      parameters:
        - name: userId
          in: path
          required: true
          schema:
            type: integer
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  description: New display name
                email:
                  type: string
                  format: email
                  description: New email address
                role:
                  type: string
                  enum: [admin, member, viewer]
                  description: New role
      responses:
        "200":
          description: User updated
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/User"

DELETE Operations

DELETE removes a resource. It is idempotent. DELETE typically returns 204 No Content with no response body. Some APIs return the deleted resource with 200 OK.

paths:
  /users/{userId}:
    delete:
      operationId: deleteUser
      summary: Delete a user
      parameters:
        - name: userId
          in: path
          required: true
          schema:
            type: integer
      responses:
        "204":
          description: User deleted successfully
        "404":
          $ref: "#/components/responses/NotFound"

Complete CRUD Example

paths:
  /users:
    get:
      operationId: listUsers
      summary: List users
      responses:
        "200":
          description: User list
    post:
      operationId: createUser
      summary: Create user
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateUser"
      responses:
        "201":
          description: Created
  /users/{userId}:
    get:
      operationId: getUser
      parameters:
        - name: userId
          in: path
          required: true
          schema:
            type: integer
      responses:
        "200":
          description: User found
    put:
      operationId: updateUser
      parameters:
        - $ref: "#/components/parameters/userIdPath"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/UpdateUser"
      responses:
        "200":
          description: Updated
    patch:
      operationId: patchUser
      parameters:
        - $ref: "#/components/parameters/userIdPath"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/PatchUser"
      responses:
        "200":
          description: Patched
    delete:
      operationId: deleteUser
      parameters:
        - $ref: "#/components/parameters/userIdPath"
      responses:
        "204":
          description: Deleted

Common Mistakes

GET with request body — Including a request body in a GET operation. GET should never have a body. Use POST or query parameters for complex input.
Wrong success code — Returning 200 for POST creates confusion. Use 201 for resource creation. Use 200 for updates that return the resource.
DELETE with response body — Returning a body for 204. DELETE with 204 should have no response body. Use 200 if returning the deleted resource.
Non-idempotent PUT — Implementing PUT that is not idempotent. PUT should produce the same result every time. Use POST for non-idempotent operations.
Missing required request body — Defining POST or PUT without required: true on the request body. Write operations almost always require a body.

Practice Questions

What response status code should a POST operation return?
Why should GET operations not have a request body?
What is the difference between PUT and PATCH?
What status code does DELETE typically return?
Which HTTP methods are idempotent?

Challenge

Design a complete set of operations for a file storage API. Include operations for file upload (POST), file download (GET), file metadata update (PATCH), file rename (PUT), file deletion (DELETE), file list (GET with filters), batch operations (POST), and file search (GET with search parameters).

FAQ

Can I use POST for operations other than creation?

Yes. POST is also used for operations that do not fit other methods, like search, batch operations, and computational actions. Document the semantics clearly.

Should I use 200 or 201 for POST?

Use 201 for resource creation. Use 200 if the POST operation is not primarily about creation (like search or batch processing).

What if my PUT operation only updates some fields?

Use PUT for full replacement and PATCH for partial updates. If your PUT behaves like partial update, reconsider the method choice.

Can an operation have multiple success responses?

Yes. For example, POST might return 201 for synchronous creation and 202 for asynchronous processing. Document both scenarios.

Is it okay to return a resource from DELETE?

Yes. Return 200 with the deleted resource body if clients need the deleted data. Return 204 if they do not. Document which you use.

Mini Project

Create a complete CRUD specification for a product catalog API. Define GET (list with filters, get by ID), POST (create product), PUT (full product update), PATCH (partial update for price, stock, status), DELETE (remove product), and any custom operations. Use appropriate status codes and response schemas for each.

What's Next

In the next lesson, you will learn how to define parameters for path, query, header, and cookie locations.

← Previous The Paths Object — Defining Endpoints and Operations Next → Parameters in OpenAPI — Path, Query, Header, and Cookie

Built by the developers of DodaTech

Doda Browser, DodaZIP & Durga Antivirus Pro

Home Browse Openapi Spec