Contents
At a glance
- Category
- Automation mechanics
- Origin
- Roy Fielding's 2000 dissertation on architectural styles for the web
- Methods
- GET read, POST create, PUT replace, PATCH partial update, DELETE remove
- Idempotent methods
- GET, PUT, DELETE. POST is not - which is why retries duplicate records
- Retry rule
- Retry 429 and 5xx with backoff; never retry 4xx, the request itself is wrong
- Always handle
- Pagination - offset, page or cursor. Cursors survive records added mid-sync
What REST means in practice
REST - representational state transfer - is an architectural style described in Roy Fielding's 2000 dissertation, and in everyday use it means an API where things are addressed as resources by URL and acted on with HTTP methods. GET /customers/42 reads customer 42. POST /customers creates one. PATCH /customers/42 updates part of it. DELETE /customers/42 removes it.
Most APIs described as RESTful do not meet Fielding's full criteria, and it does not matter. What you need is the working vocabulary: resources in the URL path, filters in the query string, the payload in JSON, authentication in a header, and the outcome in the status code.
Methods and status codes worth knowing
The methods carry meaning that affects reliability. GET and DELETE are idempotent - repeating them has the same effect as doing them once. PUT is idempotent because it replaces the whole resource. POST is not, which is exactly why a retried POST can create a duplicate customer, and why idempotency keys exist.
Status codes group by first digit. 2xx succeeded - 200 OK, 201 Created, 204 No Content. 3xx redirects. 4xx means you got it wrong: 400 malformed request, 401 not authenticated, 403 authenticated but not permitted, 404 not found, 409 conflict, 422 valid syntax but invalid content, and 429 too many requests, which is a rate limit. 5xx means the server failed. The practical rule for automation: retry 429 and 5xx with backoff, do not retry 4xx because the request itself is wrong and will be wrong again.
The quirks of real APIs
Documentation describes the ideal; production has details. Pagination is the big one - collections come back in pages, via offset, page number or an opaque cursor, and a sync that ignores it silently processes only the first page. Cursors are the most reliable because they cope with records being added mid-sync.
Partial updates vary: some APIs treat PATCH properly, others require the whole object on PUT and will blank any field you omit, which is how automations quietly erase data nobody asked them to touch. Errors vary too - some return 200 with an error inside the body, which defeats naive error handling. And field names in responses often differ from the ones in requests. Capture a real response and build against it.
Cost and performance
The cost of a REST integration is mostly call count. One record per call means a thousand records is a thousand calls, subject to rate limits and, on per-action automation platforms, a thousand billing units. Check whether the API offers bulk or batch endpoints before building a loop - they frequently exist and are frequently undocumented in the getting-started guide.
REST's other cost is over-fetching: you get the whole resource whether you wanted three fields or thirty. That is the specific problem GraphQL was designed to solve, and it is worth caring about when responses are large and volume is high.
What you should know
For automation work, three habits pay for themselves repeatedly. Always handle pagination, even when today's dataset fits in one page. Always distinguish 4xx from 5xx in your error handling, because retrying a 400 forever is pure waste. And always log the status code and raw body of failed calls - the body usually names the exact field that was wrong, and reading it takes seconds where guessing takes an afternoon.
REST API FAQ
What is a REST API?
A web API where things are addressed as resources by URL and acted on with HTTP methods: GET to read, POST to create, PATCH or PUT to update, DELETE to remove. Payloads are usually JSON and the outcome is carried in the status code.
What do the HTTP status codes mean?
2xx succeeded, 3xx redirect, 4xx your request was wrong, 5xx the server failed. The ones that matter most in automation are 401 not authenticated, 403 not permitted, 404 not found, 422 invalid content and 429 rate limited.
Which errors should my automation retry?
429 and 5xx, with exponential backoff and jitter, because those are transient. Never retry a 4xx other than 429 - the request is malformed, unauthorised or pointing at something that does not exist, and repeating it will fail identically while burning your rate limit.
What is the difference between PUT and PATCH?
PUT replaces the whole resource, so any field you omit may be blanked. PATCH updates only the fields you send. Many APIs implement this loosely, so check the documentation - accidentally clearing fields with a PUT is a common and quietly destructive automation bug.
Why is my sync only getting the first 20 records?
Pagination. The API returns a page at a time and expects you to request the next one via an offset, page number or cursor. Handle it even when today's dataset fits in one page, because the day it does not, the failure is silent rather than an error.
Is REST better than GraphQL?
Different, not better. REST is simpler, universally supported by automation platforms and easier to cache. GraphQL lets you fetch exactly the fields you need in one round trip, which matters for large responses and nested data. Use whichever the vendor offers.
Primary source
Fielding - Architectural Styles and the Design of Network-based Software Architectures
Checked August 2026. Anything priced or rate-limited moves, so verify against the source before you budget.
Want this built rather than explained?
Knowing what rest api means is one thing; having it running in your business is another. We scope one workflow at a time, quote a fixed price in writing after a free consult, build it, and hand it over with documentation you own.
