REST API Fundamentals: Methods, Status Codes, and Headers

Anatomy of a request

Every REST call starts with a URL. Here is a typical one, broken into its parts:

• Scheme: use https. Plain http sends credentials and data in clear text and is only appropriate for local development.
• Host and port: where the service lives. The port is omitted when it's the default (443 for HTTPS).
• Path: identifies the resource. /v1/orders is the collection; /v1/orders/1042 is one member of it. The v1 is a version, a common convention that lets the provider change the API without breaking existing consumers.
• Query string: optional key=value pairs, separated by &, used to filter, sort, or paginate. Values must be URL-encoded (a space becomes %20).

Older services often expose a single endpoint with parameters, for example http://localhost:8080/OrderStatus?ParmA=1&Parm2=B. That still works as an HTTP call, but it's closer to a remote procedure than to resource-oriented REST. You'll see both styles in practice.

HTTP methods

The method tells the server what you want to do with the resource.

* Safe: doesn't change anything on the server. ** Idempotent: sending the same request several times has the same effect as sending it once.

Idempotency matters when a call times out and you don't know whether it succeeded. Retrying a GET, PUT, or DELETE is safe. Retrying a POST can create a duplicate order, so many APIs accept an Idempotency-Key header to let you retry safely. Check your provider's documentation.

PUT and PATCH are often confused. PUT replaces the whole resource, so fields you leave out may be cleared. PATCH sends only the fields that change. Some APIs support only one of them, and some use PUT for partial updates anyway, so confirm the behavior before relying on it.

Status codes

Every response begins with a three-digit status code. The first digit tells you the category; the rest give detail.

A few distinctions trip people up:

• 401 vs. 403: 401 means the server doesn't know who you are (missing or invalid credentials). 403 means it knows who you are and you're not allowed.
• 400 vs. 422: 400 usually means the request is malformed (bad JSON). 422 means it parsed but failed validation (for example, a negative quantity).
• 202 Accepted: the request was received but isn't finished. Look for a status URL in the response, often in the Location header.

Headers

Headers are name/value pairs that carry metadata about the request or response. They don't change what you're asking for; they describe the context. These are the ones you'll use most:

Header names are case-insensitive. Services can also define custom headers, conventionally prefixed with X- in older APIs.

Request and response bodies

GET and DELETE requests normally have no body. POST, PUT, and PATCH do, and the Content-Type header must match what you send. A JSON body looks like this:

{
  "customerId": "C-381",
  "items": [
    { "sku": "WID-100", "qty": 12 }
  ]
}

A common mistake is sending JSON without Content-Type: application/json. The server may then reject the request with 415 Unsupported Media Type or silently ignore the body.

End-to-end example

This example creates an order, then reads it back. The host and fields are illustrative; substitute your provider's.

1. Create the order

curl

curl -i -X POST https://api.example.com/v1/orders \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{"customerId":"C-381","items":[{"sku":"WID-100","qty":12}]}'

Response

HTTP/1.1 201 Created
Location: /v1/orders/1042
Content-Type: application/json

{ "id": 1042, "status": "pending", "customerId": "C-381" }

The 201 tells you the order exists, and Location tells you where to find it.

2. Read it back

JavaScript (fetch)

const res = await fetch("https://api.example.com/v1/orders/1042", {
  headers: {
    Authorization: `Bearer ${token}`,
    Accept: "application/json",
  },
});

if (!res.ok) {
  throw new Error(`Request failed: ${res.status} ${res.statusText}`);
}

const order = await res.json();
console.log(order.status); // "pending"

Python (requests)

import requests

res = requests.get(
    "https://api.example.com/v1/orders/1042",
    headers={"Authorization": f"Bearer {token}", "Accept": "application/json"},
    timeout=10,
)
res.raise_for_status()  # raises on 4xx/5xx
order = res.json()
print(order["status"])

Note the res.ok check in JavaScript. fetch only rejects its promise on network failure, so a 404 or 500 still "succeeds" unless you check the status yourself. In Python, always set a timeout; requests waits indefinitely by default.

3. Filter a collection

GET /v1/orders?status=shipped&limit=25&sort=-createdAt

Collection endpoints usually support filtering, sorting, and pagination through query parameters. The names vary by provider, so check the API reference.

Handling errors

Good error handling in a REST client comes down to deciding, per status code, whether to fix, retry, or give up:

Many APIs return a structured error body. Parse and log it rather than only the status code:

{
  "error": {
    "code": "invalid_quantity",
    "message": "qty must be greater than 0",
    "field": "items[0].qty"
  }
}

REST vs. SOAP

REST is usually the lighter option, but it isn't always the right one. The table summarizes the trade-offs; see SOAP Basics for the other side.

Strengths of REST: lightweight, human-readable, cacheable, easy to build, test, and maintain.

Limitations to plan for:

• No single built-in security standard. You assemble it from HTTPS and an auth scheme, so the quality depends on the provider's implementation.
• Tied to HTTP semantics. That's ideal for request/response APIs, but awkward for long-running or event-driven work, which usually needs 202 Accepted plus polling, or webhooks.
• No enforced contract. Without a published spec, you rely on documentation staying accurate.

REST in CIC Studio

In CIC Studio, you call REST services with the Web Service Consumer object. The concepts above map directly onto it: the URL, method, and headers you've just read about are what you configure, and the HTTP header information is used in the object's related Request and Response actions.

To go further:

• Web Service Consumer object
• Retrieving HTTP response details with a Web Service Consumer (REST)
• Cleo Developer Documentation

Troubleshooting checklist

When a call doesn't behave, work through these in order:

1. Reproduce it with curl. If it works there but not in your code, the problem is in how your client builds the request.
2. Check the status code first, then the response body. The body usually names the problem.
3. Verify the URL. Look for a missing version segment, a trailing slash the server cares about, or unencoded characters in the query string.
4. Verify the method. 405 Method Not Allowed means the endpoint exists but not for that method.
5. Verify headers. Confirm Authorization is present and unexpired, and that Content-Type matches the body.
6. Validate the body as well-formed JSON and compare field names and types to the API reference.
7. Check for timeouts and rate limits if failures are intermittent.

Frequently Asked Questions

1. Is REST a protocol? 
   
   No. REST is a set of design constraints. HTTP is the protocol, and a "RESTful" API is one that uses HTTP in line with those constraints.
    
2. Do I have to use JSON?
   
   No, but you almost always will. The provider decides the supported formats, and the Content-Type and Accept headers tell each side which one is in use.
    
3. Should I use PUT or POST to create something?
   
   Use POST when the server assigns the identifier (POST /orders). Use PUT when you choose the identifier yourself and want the call to be safely repeatable (PUT /orders/1042).
    
4. Why did I get a 200 with an error in the body?
   
   Some APIs don't follow HTTP semantics strictly and return 200 with an error payload.  Read the provider's documentation and check the body as well as the status.