APIsProgramming and Application SecurityBeginner

HTTP methods, URLs, headers and status codes for APIs

By Mohamed Fayas 9 min readUpdated 8 October 2026

In short: Every REST call combines a method, a URL, some headers and sometimes a body. The method says what to do, the URL says which resource, and headers carry the content type and credentials. The status code in the reply tells you whether it worked and, if not, whose fault it was.

The parts of a URL

Take https://nms.example.com:443/api/v1/devices?site=london&limit=50. It breaks down into:

Scheme: https. Always use HTTPS for APIs so credentials and data are encrypted with TLS (Transport Layer Security).
Host and port: nms.example.com on port 443, the HTTPS default.
Path: /api/v1/devices, the resource. The v1 is a version, so the provider can release v2 without breaking your scripts.
Query string: everything after ?, used to filter, sort and page results. Pairs are separated by &.

Special characters in query values must be percent-encoded; the site’s URL encoder shows how.

Figure 1. An HTTP request is a start line, a set of headers, a blank line and an optional body.

HTTP methods

Method	Purpose	Has body?	Idempotent?
GET	Read a resource or list	No	Yes
POST	Create a new resource or trigger an action	Yes	No
PUT	Replace a resource completely	Yes	Yes
PATCH	Change some fields of a resource	Yes	Not guaranteed
DELETE	Remove a resource	Usually no	Yes

Idempotent means that sending the same request twice leaves the system in the same state as sending it once. That matters when a network glitch makes you unsure whether a request arrived: retrying a PUT or DELETE is safe, but retrying a POST might create a duplicate VLAN or ticket. Some APIs accept an idempotency key header on POST to prevent this.

GET    /api/v1/vlans            list all VLANs
GET    /api/v1/vlans/20         read VLAN 20
POST   /api/v1/vlans            create a VLAN (JSON body)
PATCH  /api/v1/vlans/20         rename VLAN 20
DELETE /api/v1/vlans/20         remove VLAN 20

Headers that matter

Headers are name-value pairs that describe the request or response. The ones you will use most:

Content-Type: application/json tells the server what format your body is in.
Accept: application/json asks for JSON back.
Authorization: Bearer <token> carries credentials. Some APIs use a custom header such as X-API-Key.
User-Agent identifies your client. A clear name helps the API owner see who is calling.
Responses may include rate-limit headers and a Retry-After value telling you how long to wait.

Reading status codes

Figure 2. The first digit of a status code tells you who has to act: 4xx means fix your request, 5xx means the server failed.

Code	Meaning	What to do
200 OK	Success with a body	Read the data
201 Created	New resource made	Note its ID or Location header
204 No Content	Success, no body	Nothing to parse
400 Bad Request	Malformed or invalid input	Check JSON and field values
401 Unauthorized	Not authenticated	Missing or expired credentials
403 Forbidden	Authenticated but not allowed	Check permissions or scopes
404 Not Found	No such resource	Check the path and ID
409 Conflict	Clashes with current state	The item may already exist
429 Too Many Requests	Rate limit hit	Back off and retry later
500 / 503	Server error or unavailable	Retry with delay; report if persistent

Tip: 401 and 403 are often confused. 401 means the server does not know who you are. 403 means it knows exactly who you are and the answer is still no.

Common mistakes

Assuming success: always check the status code before using the body.
Retrying every error: retry 429 and 5xx with a growing delay, but fix 4xx errors rather than repeating them.
Sending JSON without Content-Type: application/json, which many servers reject with 400 or 415.
Putting secrets in the query string, where they end up in proxy and server logs. Use headers instead.

Practice

Which method would you use to change only the description of an existing interface resource?

PATCH, because it updates some fields without replacing the whole resource.

Your script gets 403 Forbidden. Your token is valid. What is the likely cause?

The token or account lacks permission (role or scope) for that resource or action.

Why is it risky to blindly retry a POST after a timeout?

POST is not idempotent, so if the first request actually succeeded, the retry may create a duplicate resource.

Key takeaways

A URL has a scheme, host, path and optional query string.
GET reads, POST creates, PUT replaces, PATCH updates part, DELETE removes.
Idempotent methods (GET, PUT, DELETE) are safe to retry; POST is not.
Content-Type, Accept and Authorization are the key request headers.
2xx success, 4xx fix your request, 5xx server problem, 429 slow down.

Tracks your learning on this device only. See your progress on the learning paths.

About the author

Mohamed Fayas

Founder of FM TecHub. CCNA certified, with a BTEC HND in Network Engineering, and BEng (Hons) in Computer Networking and Cloud Security. He writes practical, plain-English guides on networking, security and cloud.

More about the author

The parts of a URL

HTTP methods

Headers that matter

Reading status codes

Common mistakes

Practice

Key takeaways

Stay up to date by email