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.

Last updated: November 2026

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.

MethodTypical resource operation under documented HTTP semantics
GETRetrieve a representation of the resource. The request is safe by definition
POSTAsk the resource to process submitted data, for example creating a new object or starting an action
PUTCreate or replace the state of the target resource at the supplied URI, as defined by the endpoint
PATCHApply a set of partial modifications, using the patch format documented for the endpoint
DELETERequest 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

StatusWhat to check next
200, 201, 204Inspect the documented result, created resource information, or absence of response content
202Work was accepted. Follow the documented task or status mechanism before reporting completion
400Check request syntax, input shape and required parameters
401Inspect credentials and the authentication challenge or documented token failure
403Inspect why the request was refused, including required privilege or subject context
429Respect a provided Retry-After value and the service’s documented rate and retry behavior
5xxInspect 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.

Test Your Knowledge

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?

A

Assume the job was not created and retry repeatedly

B

Determine whether the original request took effect using the endpoint’s documented lookup or operational evidence

C

Switch to GET with an action query parameter to create the same job

D

Replace the expected job ID with a different one and retry automatically

Test Your Knowledge

An endpoint returns 202 after accepting a connector job and includes a status reference. What can the integration report at this point?

A

It verified the completed target change

B

The server rejected authentication

C

The job was accepted, and its final result needs the documented status and target checks

D

The job has been removed from the service

Sections you finish are checked off in the contents.