Using HTTP APIs Safely
Key Takeaways
Read the endpoint contract for method, resource, version, media type, permissions and response.
GET is safe by definition. PUT and DELETE are idempotent in their intended effect. Treat POST and PATCH retries according to the contract.
Check asynchronous acceptance, pagination and throttling before declaring the operation complete.
Use the documented bearer access token for protected API calls. A SailPoint personal access token supplies credentials to obtain that access token.
Read the operation before sending it
A representational state transfer (REST) API commonly exposes identifiable resources through Hypertext Transfer Protocol (HTTP). Read the actual operation description. Identify the resource by path and required identifiers. Check the version, allowed query parameters, request body schema and media type. Identify which credentials and permissions the requester needs. A list endpoint and a detail endpoint can have different permissions and response shape. Product documentation determines what the specific service supports.
| Method | Typical resource operation under documented HTTP semantics |
|---|---|
GET | Retrieve a representation of the resource. The request is safe by definition |
POST | Ask the resource to process submitted data, for example creating a new object or starting an action |
PUT | Create or replace the state of the target resource at the supplied URI, as defined by the endpoint |
PATCH | Apply a set of partial modifications, using the patch format documented for the endpoint |
DELETE | Request removal of the association between the target URI and its current functionality |
Safe methods have read-only intended semantics. Idempotency means that repeating an identical request has the same intended effect as sending it once. PUT, DELETE and safe HTTP methods have that property. The second response can differ. An already deleted resource may return 404 to a later request. POST and PATCH lack a general guarantee of idempotency, even though particular endpoints or patches can supply safe retry properties. Check the operation contract and ensure the intended target and preconditions still apply.
Interpret the status and body
| Status | What to check next |
|---|---|
200, 201, 204 | Inspect the documented result, created resource information, or absence of response content |
202 | Work was accepted. Follow the documented task or status mechanism before reporting completion |
400 | Check request syntax, input shape and required parameters |
401 | Inspect credentials and the authentication challenge or documented token failure |
403 | Inspect why the request was refused, including required privilege or subject context |
429 | Respect a provided Retry-After value and the service’s documented rate and retry behavior |
5xx | Inspect the server error, operation state and the endpoint’s safe recovery policy |
A response includes headers and may include content. If an endpoint returns results in pages, follow its documented pagination mechanism. Confirm completion before calling the assembled results a full inventory. If a response contains 100 rows and a next-page token, a successful status applies to that page. Preserve the relevant filters and request the subsequent page with the documented token. Use documented filters and sort behavior to keep a narrow call reproducible. For a modification, record the resource ID returned or used. If an endpoint supports conditional updates with entity tags, retain the tag from the resource read and use it in the documented condition. For example, a server evaluating If-Match on an update can return 412 when the resource has changed. Re-read the resource and resolve the concurrent edit before sending the intended change again.
Work the ambiguous operation
An integration submits POST to create a report job. The server accepts the request, but the response is lost and the integration times out. The job may already exist. Before retrying, use the service’s documented status lookup or idempotency behavior if it provides one. If there is no way to determine the original effect or safely deduplicate, do not retry automatically. A successful 202 when the response is delivered would establish acceptance, so the caller still needs job status to claim success.
Identity Security Cloud exposes APIs with OAuth 2.0. For an endpoint using user-associated personal access token (PAT) credentials, exchange the client ID and secret for an access token, then use that access token in the bearer header required by the API. Check privileges and scopes for the specific operation. Store credential material securely and redact it in examples and diagnostic output. For a 403 after a valid token, inspect endpoint authorization and applicable user context. Issue a replacement token only when doing so addresses the diagnosed condition.
See HTTP Semantics, the HTTP PATCH specification, HTTP 429, and SailPoint’s authentication and authorization documentation.
A POST to a job-creation endpoint times out before its response is received. The endpoint has no documented idempotency support. What is the correct first action before repeating the write?
Assume the job was not created and retry repeatedly
Determine whether the original request took effect using the endpoint’s documented lookup or operational evidence
Switch to GET with an action query parameter to create the same job
Replace the expected job ID with a different one and retry automatically
An endpoint returns 202 after accepting a connector job and includes a status reference. What can the integration report at this point?
It verified the completed target change
The server rejected authentication
The job was accepted, and its final result needs the documented status and target checks
The job has been removed from the service
Sections you finish are checked off in the contents.