The requirement level keywords "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" used in this document (case insensitive) are to be interpreted as described in RFC 2119.

The purpose of our "RESTful API guidelines" is to define standards to successfully establish "consistent API look and feel" quality. The SailPoint API Guild drafted and owns this document. Teams are responsible to fulfill these guidelines during API development and are encouraged to contribute to guideline evolution via pull requests.

These guidelines will, to some extent, remain work in progress as our work evolves, but teams can confidently follow and trust them.

In case guidelines are changing, following rules apply:

Furthermore you should keep in mind that once an API becomes public externally available, it has to be re-reviewed and changed according to current guidelines - for sake of overall consistency.

Comparing SOA web service interfacing style of SOAP vs. REST, the former tend to be centered around operations that are usually use-case specific and specialized. In contrast, REST is centered around business (data) entities exposed as resources that are identified via URIs and can be manipulated via standardized CRUD-like methods using different representations, and hypermedia. RESTful APIs tend to be less use-case specific and come with less rigid client / server coupling and are more suitable for an ecosystem of (core) services providing a platform of APIs to build diverse new business services. We apply the RESTful web service principles to all kind of application (micro-) service components, independently from whether they provide functionality via the internet or intranet.

An important principle for API design and usage is Postel’s Law, aka The Robustness Principle (see also RFC 1122):

Readings: Some interesting reads on the RESTful API design style and service architecture:

At SailPoint, we want to deliver products to our (internal and external) customers which can be consumed like a service. Platform products provide their functionality via (public) APIs; hence, the design of our APIs should be based on the API as a Product principle:

Embracing 'API as a Product' facilitates a service ecosystem, which can be evolved more easily and used to experiment quickly with new business ideas by recombining core capabilities. It makes the difference between agile, innovative product service business built on a platform of APIs and ordinary enterprise integration business where APIs are provided as "appendix" of existing products to support system integration and optimised for local server-side realization.

Understand the concrete use cases of your customers and carefully check the trade-offs of your API design variants with a product mindset. Avoid short-term implementation optimizations at the expense of unnecessary client side obligations, and have a high attention on API quality and client developer experience.

API as a Product is closely related to our API First principle (see next chapter) which is more focused on how we engineer high quality APIs.

API First is one of our engineering and architecture principles. In a nutshell API First requires two aspects:

By defining APIs outside the code, we want to facilitate early review feedback and also a development discipline that focus service interface design on…​

Moreover, API definitions with standardized specification format also facilitate…​

Elements of API First are also this API Guidelines and a standardized API review process as to get early review feedback from peers and client developers. Peer review is important for us to get high quality APIs, to enable architectural and design alignment and to supported development of client applications decoupled from service provider engineering life cycle.

It is important to learn, that API First is not in conflict with the agile development principles that we love. Service applications should evolve incrementally — and so its APIs. Of course, our API specification will and should evolve iteratively in different cycles; however, each starting with draft status and early team and peer review feedback. API may change and profit from implementation concerns and automated testing feedback. API evolution during development life cycle may include breaking changes for not yet productive features and as long as we have aligned the changes with the clients. Hence, API First does not mean that you must have 100% domain and requirement understanding and can never produce code before you have defined the complete API and get it confirmed by peer review.

On the other hand, API First obviously is in conflict with the bad practice of publishing API definition and asking for peer review after the service integration or even the service productive operation has started. It is crucial to request and get early feedback — as early as possible, but not before the API changes are comprehensive with focus to the next evolution step and have a certain quality (including API Guideline compliance), already confirmed via team internal reviews.

You must design your APIs consistently with these guidelines; use our API linter for automated rule checks, but not every rule can be automated.

You should follow the API First Principle, more specifically:

We use the OpenAPI specification as the standard to define API specification files. The specification file must use OpenAPI 3. Swagger 2 is not supported.

The API specification files should be subject to version control using a source code management system.

You must publish the component API specification with the deployment of the implementing service, and, hence, make it discoverable for the appropriate group via our API Portal.

Start each specification file with the OpenAPI 3.0 version:

Within the API specification, you must give each operation a description with enough information for a consumer to use it correctly. Include the following when they apply:

Example:

In addition to the API Specification, it is good practice to provide a separate API user manual to improve client developer experience, especially of engineers that are less experienced in using this API. A helpful API user manual typically describes the following API aspects:

The user manual must be published online, e.g. via our documentation hosting platform service. Please do not forget to include a link to the API user manual into the API specification using the #/externalDocs/url property.

Every query/path parameter and request/response property in the API specification must have a description.

A parameter description must be at least 8 characters long.

Every query/path parameter and request/response property in the API specification must have an accurate example. An accurate example will show the API consumer what an input/output value will realistically look like, and could even be used in a real request/response. However, take care to not use personally identifiable information or secrets in examples.

Every operation (POST, PUT, PATCH, etc) may define one or more operation level examples.

A parameter can give its example in example, schema.example or examples.

These properties do not need their own example:

Use a value that looks real:

comment has nullable: true, and the items schema of accessItemIds has an example. So these properties do not need their own example.

Every operation must have a summary. A missing summary is an error. The five-word limit is a recommendation. The linter shows a warning when a summary has more than five words.

Certain tools, like Postman, have a limit on how many words can be displayed within the operation summary. It is helpful for consumers to have short summaries that describe the operation at its most basic level to improve readability for consumers.

operationId is a unique string used to identify an operation. These IDs must be unique among all operations described in your API.

Certain tools, like the OpenAPI Generator use this value to name the corresponding methods in code.

The following listAccessProfiles is an example of an operationId.

Use this guide when creating your operationIds. Your operationId must start with one of the approved values for each method.

GET methods that return a list: a top-level array, or an object with an items array (see MUST always return JSON objects as top-level data structures )

GET methods that return a single result, that is, any other response

POST methods

PUT methods

PATCH methods

DELETE methods

For operations in an API collection under apis/, the operationId must also end with the collection version. See MUST end operationIds in an API collection with the collection version .

Each operation must be assigned exactly one tag that categorizes it. No operation should have more than one tag.

This tag must also exist in the root specification.

Certain tools, such as the API Schema Validator and developer.sailpoint.com, rely on x-sailpoint-resource-operation-id to accurately locate and reference the required values for path parameters.

When validating API responses, the tool needs to make requests to an endpoint that requires a path parameter (such as a resource id). Without a valid operationId, there is no way to programmatically determine how to retrieve a valid identifier from the system. By defining x-sailpoint-resource-operation-id, the validator can look up the appropriate operation to call, fetch a valid resource identifier, and then use it to execute the request for validation. This ensures that response validation is performed on actual data from the system rather than using placeholder or manually provided values.

Uses the x-sailpoint-resource-operation-id value to improve API discoverability and documentation by linking path parameters to their respective operations. When an API requires a path parameter, such as a unique resource identifier (id), this key helps determine how the value can be retrieved. If an operation exists to list or search for the resource, its operationId can be referenced, allowing developers to programmatically obtain the required identifier before making a request to an endpoint that depends on it.

This rule does not apply in the following cases:

Enums in Path Parameters – If the path parameter is an enum, the set of possible values is predefined and does not require lookup from an external resource. Tools can iterate through the available values without needing an associated operationId. The API Schema Validator and other tools can directly use the enum values to construct valid API requests, eliminating the need for additional lookups.

User-Defined Path Parameters – If the path parameter represents a value entirely determined by the user (e.g., specifying a filename when downloading or saving a file), there is no need to retrieve a resource identifier from the system. Since these values are not tied to any existing API resource, defining x-sailpoint-resource-operation-id would not be meaningful or applicable.

API specification files must contain only ASCII characters. Non-ASCII characters, such as curly quotes, em-dashes and non-breaking spaces, break some code generators and documentation tools.

Use the ASCII form instead. For example, use ' and " instead of curly quotes, and use - instead of an em-dash.

The tags list in the root specification must be sorted in alphabetical order by name. A sorted list makes it easy to find a tag and to see when a tag is a duplicate.

Every tag in the tags list of the root specification must have a description. The developer portal and the SDK generators show the tag description as the introduction to the group of operations with that tag.

The description must tell the consumer what the resource is and what they can do with the operations in the tag. If a concept is necessary to understand the resource, explain it with a short example.

Path and schema files in a versioned folder (for example v2024, v2025 or v2026) must only use $ref to files in the same version folder. A reference to another version folder couples the two versions. A change to one version can then change the other version without notice.

If you need a schema from another version, copy it into your version folder.

In this example, the path file is in the v2025 folder:

API specification files must not contain text in the form ${…​}. The developer portal uses Docusaurus, and Docusaurus reads ${…​} as a variable. If the variable is not defined, the documentation build fails.

If you need to show a template value in a description or example, use a different form, for example {{value}} or <value>.

An operation in an API collection under apis/ must have an operationId that ends with the collection version. The version comes from the /vN segment of the path that the collection openapi.yaml file maps to the path file. The suffix uses an uppercase V and the version number, for example V1 or V2.

This rule is in addition to MUST provide a valid operationId in camelCase for each operation .

Operation descriptions must not contain HTML tags such as <br>, <b> or <a>. Use markdown instead. The developer portal and the SDK generators render markdown, but they do not render HTML in the same way.

Use U.S. English spelling in names, enum values, descriptions and examples.

API specifications must contain the following OpenAPI meta information to allow for API management:

Each API must be classified with respect to the intended target audience supposed to consume the API, to facilitate differentiated standards on APIs for discoverability, changeability, quality of design and documentation, as well as permission granting. We differentiate the following API audience groups with clear organizational and legal boundaries:

internal-company external-public

Example:

Every public API endpoint must be secured using OAuth 2.0. We have defined two security schemas, userAuth and applicationAuth. In the rare case that an endpoint does not require authentication, and is completely open to the public, then an empty object can be used instead.

Each endpoint must select one or both of the security schemes depending on which one(s) it supports. For example, if an endpoint supports only userAuth, then the path would be defined as follows:

If the endpoint supports both security schemes, then it would be defined as follows:

If the endpoint does not require authentication, then it would be defined as follows:

Each endpoint must document every scope needed to access the endpoint. See Defining Scopes for API Authorization for more information on adding new scopes.

To appropriately document a scope on an endpoint, use the following OpenAPI properties:

A full example on an endpoint might look like this:

Each endpoint that specifies userAuth as one of the allowed security types must also document the user levels required to access the endpoint. See the user level matrix for more information.

To appropriately document user level(s) on an endpoint, use the x-sailpoint-userLevels attribute in the path definition. The technical name must be used as seen in the user level matrix (ex. ORG_ADMIN instead of Admin). If an endpoint can be called by a user with no elevated user levels, use the value "Any" instead of listing all user levels.

A full example on an endpoint might look like this:

If an API collection requires additional product licenses to enable the feature, then each required license must be documented in the API collection description.

A scope has three parts, separated by colons: <product>:<resource>:<access>.

Each scope must match this pattern:

Examples: idn:access-profile:read, idn:task-definition:manage.

Change APIs, but keep all consumers running. Consumers usually have independent release lifecycles, focus on stability, and avoid changes that do not provide additional value. APIs are contracts between service providers and service consumers that cannot be broken via unilateral decisions.

There are two techniques to change APIs without breaking them:

We strongly encourage using compatible API extensions and discourage versioning (see SHOULD avoid versioning and MUST use URI versioning below). The following guidelines for service providers (SHOULD prefer compatible extensions) and consumers (MUST prepare clients to accept compatible API extensions) enable us (having Postel’s Law in mind) to make compatible changes without versioning.

Note: There is a difference between incompatible and breaking changes. Incompatible changes are changes that are not covered by the compatibility rules below. Breaking changes are incompatible changes deployed into operation, and thereby breaking running API consumers. Usually, incompatible changes are breaking changes when deployed into operation. However, in specific controlled situations it is possible to deploy incompatible changes in a non-breaking way, if no API consumer is using the affected API aspects (see also Deprecation guidelines).

Hint: Please note that the compatibility guarantees are for the "on the wire" format. Binary or source compatibility of code generated from an API definition is not covered by these rules. If client implementations update their generation process to a new version of the API definition, it has to be expected that code changes are necessary.

A team wants to show the full name of an identity under a new name.

API designers should apply the following rules to evolve RESTful APIs for services in a backward-compatible way:

Service clients should apply the robustness principle:

Service clients must be prepared for compatible API extensions of service providers:

A client reads this response. The API definition does not have riskScore yet, and SUSPENDED is a new value of status. The client ignores riskScore and keeps it if it sends the object back in a PUT request. The client uses its default behavior for the unknown SUSPENDED value.

Designers of service provider APIs should be conservative and accurate in what they accept from clients:

Not ignoring unknown input fields is a specific deviation from Postel’s Law (e.g. see also
The Robustness Principle Reconsidered) and a strong recommendation. Servers might want to take different approach but should be aware of the following problems and be explicit in what is supported:

In specific situations, where a (known) input field is not needed anymore, it either can stay in the API definition with "not used anymore" description or can be removed from the API definition as long as the server ignores this specific parameter.

In this example, the client sends descripton, a misspelled property name. The server does not ignore it. It returns 400 with the standard error response object (see MUST use a standard error response object).

Define exact constraints for each input property:

In a response body, you must always return a JSON object (and not e.g. an array) as a top level data structure to support future extensibility. JSON objects support compatible extension by additional attributes. This allows you to easily extend your response and e.g. add pagination later, without breaking backwards compatibility. See MAY use pagination links where applicable for an example.

Maps (see SHOULD define maps using additionalProperties), even though technically objects, are also forbidden as top level data structures, since they don’t support compatible, future extensions.

For a list operation, put the list in an items array in the response object:

Many existing list operations return a top-level array. A change to the shape of an existing response breaks clients (see MUST not break backward compatibility), so these operations keep the array. The API linter reports them. Turn off the rule on each existing operation with the x-sailpoint-lint-ignore extension, and say what to do in the next version:

Each new list operation must return an object.

The OpenAPI specification is not very specific on default extensibility of objects, and redefines JSON-Schema keywords related to extensibility, like additionalProperties. Following our compatibility guidelines, OpenAPI object definitions are considered open for extension by default as per Section 5.18 "additionalProperties" of JSON-Schema.

When it comes to OpenAPI, this means an additionalProperties declaration is not required to make an object definition extensible:

API formats must not declare additionalProperties to be false, as this prevents objects being extended in the future.

Note that this guideline concentrates on default extensibility and does not exclude the use of additionalProperties with a schema as a value, which might be appropriate in some circumstances, e.g. see SHOULD define maps using additionalProperties.

Discouraged:

Recommended:

When changing your RESTful APIs, do so in a compatible way and avoid generating additional API versions. Multiple versions can significantly complicate understanding, testing, maintaining, evolving, operating and releasing our systems (supplementary reading).

If changing an API can’t be done in a compatible way, then proceed in one of these three ways:

A team wants to return the manager of each account.

SailPoint uses URI versioning with the following structure:

/v{version number}

Ex. /v3, /v4, etc.

Note: Beta APIs fall under /beta.

All versioned APIs must adhere to the following requirements

Breaking changes include, but are not limited to, the following:

If in doubt, ask! Call out any uncertainties during API review or during the design process.

Non-breaking changes may be added to an existing live version. Here are some examples of non-breaking changes:

In this example, description is optional in the live /v3 version.

Before shutting down an API, version of an API, or API feature the producer should make sure that all clients have given their consent on a sunset date. Producers should help consumers to migrate to a potential new API or API feature by providing a migration manual and clearly state the time line for replacement availability and sunset (see also SHOULD add Deprecation and Sunset header to responses). The producer should wait for all clients of a sunset API feature to migrate before shutting down the deprecated API.

The API deprecation must be part of the API specification.

If an API endpoint (operation object), an input argument (parameter object), an in/out data object (schema object), or on a more fine grained level, a schema attribute or property should be deprecated, the producers must set deprecated: true for the affected element and explain the deprecation:

If a future shut down is planned, the producer must provide a sunset date and document in details what consumers should use instead and how to migrate.

This example deprecates an operation, a query parameter and a property. Each explanation gives the sunset date and the replacement.

Owners of an API, API version, or API feature used in production that is scheduled for sunset must monitor the usage of the sunset API, API version, or API feature in order to observe migration progress and avoid uncontrolled breaking effects on ongoing consumers. See also MUST monitor API usage.

Must notify customers using deprecated APIs on a timely basis to help them move onto newer APIs, especially as the API moves closer to its sunset date.

During the deprecation phase, the producer should add a Deprecation: <date-time> (see draft: RFC Deprecation HTTP Header) and - if also planned - a Sunset: <date-time> (see RFC 8594) header on each response affected by a deprecated element (see MUST reflect deprecation in API specifications).

The Deprecation header can either be set to true - if a feature is retired -, or carry a deprecation time stamp, at which a replacement will become/became available and consumers must not on-board any longer (see MUST not start using deprecated APIs). The optional Sunset time stamp carries the information when consumers latest have to stop using a feature. The sunset date should always offer an eligible time interval for switching to a replacement feature.

If multiple elements are deprecated the Deprecation and Sunset headers are expected to be set to the earliest time stamp to reflect the shortest interval consumers are expected to get active.

Note: adding the Deprecation and Sunset header is not sufficient to gain client consent to shut down an API or feature.

Hint: In earlier guideline versions, we used the Warning header to provide the deprecation info to clients. However, Warning header has a less specific semantics, will be obsolete with draft: RFC HTTP Caching, and our syntax was not compliant with RFC 7234 — Warning header.

Clients should monitor the Deprecation and Sunset headers in HTTP responses to get information about future sunset of APIs and API features (see SHOULD add Deprecation and Sunset header to responses). We recommend that client owners build alerts on this monitoring information to ensure alignment with service owners on required migration task.

Hint: In earlier guideline versions, we used the Warning header to provide the deprecation info (see hint in SHOULD add Deprecation and Sunset header to responses).

In this example, the client gets this response. It logs the operation and the two dates, and it sends an alert to the client owner.

Clients must not start using deprecated APIs, API versions, or API features.

In this example, the sourceName property of Account is deprecated, and sourceId replaces it.

These guidelines provides recommendations for defining JSON data at SailPoint. JSON here refers to RFC 7159 (which updates RFC 4627), the "application/json" media type and custom JSON media types defined for APIs. The guidelines clarifies some specific cases to allow SailPoint JSON data to have an idiomatic form across teams and services.

The first some of the following guidelines are about property names, the later ones about values.

Names of arrays should be pluralized to indicate that they contain multiple values. This implies in turn that object names should be singular.

Property names are restricted to ASCII strings. The first character must be a lower case letter, there must not be any spaces, and new words should start with a capital letter instead of a space. For example, “new client table” would be “newClientTable” in camelCase.

“ID” is common in field names, and must be presented in camel case as follows:

Enumerations must be represented as string typed OpenAPI definitions of request parameters or model properties. Enum values (using enum or x-extensible-enum) need to consistently use the upper-snake case format, e.g. VALUE or YET_ANOTHER_VALUE. This approach allows to clearly distinguish values from properties or other elements.

Exception: This rule does not apply for case sensitive values sourced from outside API definition scope, e.g. for language codes from ISO 639-1, or when declaring possible values for a rule 137 [sort parameter].

A "map" here is a mapping from string keys to some other type. In JSON this is represented as an object, the key-value pairs being represented by property names and property values. In OpenAPI schema (as well as in JSON schema) they should be represented using additionalProperties with a schema defining the value type. Such an object should normally have no other defined properties.

The map keys don’t count as property names in the sense of rule 118, and can follow whatever format is natural for their domain. Please document this in the description of the map object’s schema.

Here is an example for such a map definition (the translations property):

An actual JSON object described by this might then look like this:

Schema based JSON properties that are by design booleans must not be presented as nulls. A boolean is essentially a closed enumeration of two values, true and false. If the content has a meaningful null value, strongly prefer to replace the boolean with enumeration of named values or statuses - for example accepted_terms_and_conditions with true or false can be replaced with terms_and_conditions with values yes, no and unknown.

All optional boolean properties must have a default value defined. If the property is required, it is not required to have a default value.

A PUT request body is an exception. In a PUT, a missing field keeps the stored value, so a default has no meaning there.

In this example, enabled is optional and has a default. locked is required, so it does not need a default.

Avoid using qualifying verbs, especially on boolean fields, e.g.

The name of a Boolean field should preferably express semantics such that true indicates a positive attribute, action, capability, etc.

When a field contains an ID or reference to an foreign object, not the parent object, the field name should suggest the value type:

For example, the following request/response for an account object uses the proper naming for object references.

“id” refers to the account object being requested, and all other object references include the object reference name (i.e. sourceId, identityId, etc.)

The name type is too generic. It does not tell the consumer which kind of type the value describes. It also collides with the type keyword of the schema, and many SDK languages reserve the word. Add the name of the resource or the concept to the name, for example workflowType or triggerType.

This rule applies to:

The id field of an object is not part of this rule. See MUST use a field name that suggests the value type when referencing an object.

This guideline is retired. It asked for a Ref suffix on each property that holds a reference object, for example managerRef. But SHOULD avoid using nested objects recommends a reference object without the suffix, for example owner, and the current APIs use both forms. To name a property that holds the ID of another object, follow MUST use a field name that suggests the value type when referencing an object.

In general, we discourage nesting DTOs inside others. This has typically led to bloated DTOs and made it complicated to enforce authorization requirements and other business rules around those nested objects. It is preferable instead for the DTO to have a field containing an id or reference that allows the nested object to be separately fetched.

It is recognized, of course, that particular use cases may require nesting objects inside each other. For example, if a UI module needs to display data from a set of 100 IdentityRequests and their child IdentityRequestItems, it makes no sense to require the UI to make one API call to get the list of IdentityRequests and then 100 additional calls to get the IdentityRequestItems for each.

It is preferable in these cases to use a summary DTO for the nested objects that contains the minimum amount of detail required to support the known or plausible use case(s). For example, if the only reason I need to include the owner of an object is so the caller can display their first and last name, then it is better to do something like the following:

One particular valid use of nested objects occurs when a DTO abstracts over a set of types that may have significantly different attributes. In this case the non-general fields of the DTO should be pushed down to a nested object, with a type field on the main object being used as a discriminator. For example, if a DTO could represent either an Access Profile or a Role, the former case could be implemented as follows:

Each optional input value must define a default value. The default tells the client which value the service uses when the client leaves out the value.

This rule applies to:

This rule does not apply to output values, that is, the properties of a response body. The service always sets an output value, so a default has no meaning there. Do not add a default to a response property.

A required input value does not need a default. A PUT request body is also an exception, because in a PUT, a missing field keeps the stored value. See MUST define a default value for boolean properties .

This query parameter is optional, so it defines a default:

In this request body, priority is optional and defines a default. name is required, so it does not need a default:

This response body does not define defaults:

All request/response schemas MUST define the “required” attribute for each property and parameter per the OpenAPI specification.

For request/response objects, see https://swagger.io/docs/specification/data-models/data-types/#required. If all properties within an object are optional, then the "required" attribute may be omitted. If the "required" attribute is present, it must not be null or an empty list.

For path and query parameters, see https://swagger.io/docs/specification/describing-parameters/

Generally, query parameters should be optional, but there are cases where a query parameter is required. In these cases, make sure to set the “required” attribute for the query parameters to true.

TBD

If a property or parameter can return null, then it must have the nullable: true OpenAPI property.

The property can then hold null in a response:

Empty array values can unambiguously be represented as the empty list, [].

Use the date and time formats defined by RFC 3339:

Note that the OpenAPI format "date-time" corresponds to "date-time" in the RFC) and 2015-05-28 for a date (note that the OpenAPI format "date" corresponds to "full-date" in the RFC). Both are specific profiles, a subset of the international standard ISO 8601.

A zone offset may be used (both, in request and responses) — this is simply defined by the standards. However, we encourage restricting dates to UTC and without offsets. For example 2015-05-28T14:07:17Z rather than 2015-05-28T14:07:17+00:00. From experience we have learned that zone offsets are not easy to understand and often not correctly handled. Note also that zone offsets are different from local times that might be including daylight saving time. Localization of dates should be done by the services that provide user interfaces, if required.

When it comes to storage, all dates should be consistently stored in UTC without a zone offset. Localization should be done locally by the services that provide user interfaces, if required.

Sometimes it can seem data is naturally represented using numerical timestamps, but this can introduce interpretation issues with precision, e.g. whether to represent a timestamp as 1460062925, 1460062925000 or 1460062925.000. Date strings, though more verbose and requiring more effort to parse, avoid this ambiguity.

Schema based JSON properties that are by design durations and intervals could be strings formatted as recommended by ISO 8601 (Appendix A of RFC 3339 contains a grammar for durations).

Examples of ISO 8601 durations and intervals:

Use JSON (RFC 7159) to represent structured (resource) data passed with HTTP requests and responses as body payload. The JSON payload must use a JSON object as top-level data structure (if possible) to allow for future extension. This also applies to collection resources, where you ad-hoc would use an array — see also MUST always return JSON objects as top-level data structures .

Additionally, the JSON payload must comply to the more restrictive Internet JSON (RFC 7493), particularly

As a consequence, a JSON payload must

TBD

You should use standard media types (defined in media type registry of Internet Assigned Numbers Authority (IANA)) as content-type (or accept) header information. More specifically, for JSON payload you should use the standard media type application/json.

You should avoid using custom media types like application/x.sailpoint.article+json. Custom media types beginning with x bring no advantage compared to the standard media type for JSON, and make automated processing more difficult.

JSON Schema and OpenAPI define several data formats, e.g. date, time, email, and url, based on ISO and IETF standards. The following table lists these formats including additional formats useful in an e-commerce environment. You must use these formats, whenever applicable. You must not use a format that is not in this table.

Remark: The API linter rejects a format that is not in this table. If you need another format, contact the Developer Relations team to add it to this table and to the linter.

This schema uses standard formats for its string and integer properties:

Use the following standard formats for country, language and currency codes:

Whenever an API defines a property of type number or integer, the precision must be defined by the format as follows to prevent clients from guessing the precision incorrectly, and thereby changing the value unintentionally:

The precision must be translated by clients and servers into the most specific language types. E.g. for the following definitions the most specific language types in Java will translate to BigDecimal for Money.amount and int or Integer for the OrderList.page_size:

The OpenAPI specification does not provide dedicated properties for defining filters, so filters must be defined in the description of the filters query param. Our users and our tooling rely on filter descriptions following a strict format. The following snippet is an example of how to properly format the description for filters.

The OpenAPI specification does not provide dedicated properties for defining sorter, so sorters must be defined in the description of the sorters query param. Our users and our tooling rely on filter descriptions following a strict format. The following snippet is an example of how to properly format the description for sorters.

Use the following common money structure:

APIs are encouraged to include a reference to the global schema for Money.

Please note that APIs have to treat Money as a closed data type, i.e. it’s not meant to be used in an inheritance hierarchy. That means the following usage is not allowed:

TBD

TBD

Example:

Examples:

We need to have a consistent look and feel for our APIs. In the case of query parameters, which can reference actual properties in the response object, camelCase preserves a consistent look and feel.

When defining a path segment for a collection, the resource name must be plural to indicate it is a collection of resources.

Example:

/users, /companies/{companyId}/employees/{employeeId}

In most cases, all resources provided by a service are part of the public API, and therefore should be made available under the root "/" base path.

If the service should also support non-public, internal APIs — for specific operational support functions, for example — we encourage you to maintain two different API specifications and provide API audience. For both APIs, you should not use /api as base path.

We see API’s base path as a part of deployment variant configuration. Therefore, this information has to be declared in the server object.

Declare the base path in the server object, not in the paths:

You must not specify paths with duplicate or trailing slashes, e.g. /customers//addresses or /customers/. As a consequence, you must also not specify or use path variables with empty string values.

Reasoning: Non standard paths have no clear semantics. As a result, behavior for non standard paths varies between different HTTP infrastructure components and libraries. This may leads to ambiguous and unexpected results during request handling and monitoring.

We recommend to implement services robust against clients not following this rule. All services should normalize request paths before processing by removing duplicate and trailing slashes. Hence, the following requests should refer to the same resource:

Note: path normalization is not supported by all framework out-of-the-box. Services are required to support at least the normalized path while rejecting all alternatives paths, if failing to deliver the same resource.

If you provide query support for searching, sorting, filtering, and paginating, you must stick to the following naming conventions:

Pagination

filters: an item will only be included in the returned array if the filters expression evaluates to true for that item. Each endpoint that implements filters must clearly define in the API spec what operations and fields are supported.

sorters: a set of comma-separated field names. Each field name may be optionally prefixed with a "-" character, which indicates the sort is descending based on the value of that field. Otherwise, the sort is ascending. Each endpoint that implements sorters must clearly define which fields are supported.

See https://developer.sailpoint.com/docs/api/standard-collection-parameters for implementation details for each of the above parameters.

Note: Additional query parameters are allowed, but effort should be made to fit them within the five listed above.

This request asks for the second page of 50 accounts, with a total count. It filters by name and sorts by name, then by creation date in descending order. The filters value is URL-encoded. Decoded, it is name sw "Admin".

The customer organization is provided in the session context that is generated on the back end, and therefore does not need to be in the URL.

The tenant name in the host name, for example https://acme.api.identitynow.com, is not part of the path.

REST is all about your resources, so consider the domain entities that take part in web service interaction, and aim to model your API around these using the standard HTTP methods as operation indicators. For example, rather than creating a specific action for completing a certification campaign, prefer to use PATCH to update the completed status of the campaign.

Request

Body

This example uses JSON Patch, where each operation specifies an op (operation type such as "replace", "add", "remove"), a path (JSON Pointer to the target field), and a value (the new value to apply). This format provides a standardized way to express partial updates to resources.

Sometimes, standard HTTP methods aren’t specific enough to indicate the action you wish to perform on a resource, or there is complex business logic on the back end that can’t be satisfied by PATCHing a single field. In these cases, it is advisable to use the following URI format for specific resource actions:

Request

TBD

As a rule of thumb resources should be defined to cover 90% of all its client’s use cases. A useful resource should contain as much information as necessary, but as little as possible. A great way to support the last 10% is to allow clients to specify their needs for more/less information by supporting filtering and embedding.

In this example, the access profile holds the fields that most clients need. It refers to the owner and the source by type, id and name. It does not embed the full owner identity or the full source configuration.

The API describes resources, so the only place where actions should appear is in the HTTP methods. In URLs, use only nouns. Instead of thinking of actions (verbs), it’s often helpful to think about putting a message in a letter box: e.g., instead of having the verb cancel in the url, think of sending a message to cancel an order to the cancellations letter box on the server side.

API resources represent elements of the application’s domain model. Using domain-specific nomenclature for resource names helps developers to understand the functionality and basic semantics of your resources. It also reduces the need for further documentation outside the API definition. For example, "sales-order-items" is superior to "order-items" in that it clearly indicates which business object it represents. Along these lines, "items" is too general.

The name /profiles does not tell if the resource is an access profile or an identity profile.

A resource identifier that is a path parameter must use only these characters: a-z, A-Z, 0-9, colon (:), period (.), underscore (_), hyphen (-) and slash (/). Other characters, for example a space or @, must be percent-encoded in the URL. Clients, gateways and servers encode and decode them in different ways, so the request can fail or reach the wrong resource.

The API linter checks the example of each path parameter.

Some API resources may contain or reference sub-resources. Sub-resources should be referenced by their name and identifier in the path segments as follows:

In order to improve the consumer experience, you should aim for intuitively understandable URLs, where each sub-path is a valid reference to a resource or a set of resources. For instance, if /partners/{partnerId}/addresses/{addressId} is valid, then, in principle, also /partners/{partnerId}/addresses, /partners/{partnerId} and /partners must be valid. Examples of concrete url paths:

Note: resource identifiers may be build of multiple other resource identifiers.

Exception: In some situations the resource identifier is not passed as a path segment but via the authorization information, e.g. an authorization token or session cookie. Here, it is reasonable to use self as pseudo-identifier path segment. For instance, you may define /employees/self or /employees/self/personal-details as resource paths —  and may additionally define endpoints that support identifier passing in the resource path, like define /employees/{emplId} or /employees/{emplId}/personal-details.

If a sub-resource is only accessible via its parent resource and may not exist without parent resource, consider using a nested URL structure, for instance:

However, if the resource can be accessed directly via its unique id, then the API should expose it as a top-level resource. For example, customer has a collection for sales orders; however, sales orders have globally unique id and some services may choose to access the orders directly, for instance:

Numerical, sequential IDs are considered a security risk because malicious actors can enumerate through the IDs to obtain unauthorized information. API producers must use GUIDs or natural keys that aren’t sequential.

TBD

There are main resources (with root url paths) and sub-resources (or nested resources with non-root urls paths). Use sub-resources if their life cycle is (loosely) coupled to the main resource, i.e. the main resource works as collection resource of the subresource entities. You should use ⇐ 3 resource levels in a path, the main resource included. More levels increase API complexity and url path length. Path parameters and version segments such as v1 or v2025 do not count as levels. (Remember, some popular web browsers do not support URLs of more than 2000 characters.)

The discouraged path has five resource levels: sources, accounts, entitlements, access-profiles and owners. Entitlements and access profiles have their own unique IDs, so expose them as top-level resources (see SHOULD consider using (non-)nested URLs).

Be compliant with the standardized HTTP method semantics summarized as follows:

Request methods in RESTful services can be…​

Note: The above definitions, of intended (side) effect allows the server to provide additional state changing behavior as logging, accounting, pre- fetching, etc. However, these actual effects and state changes, must not be intended by the operation so that it can be held accountable.

Method implementations must fulfill the following basic properties according to RFC 7231:

DELETE is idempotent. In this example, the second request returns a different status code. But the server state is the same after one request or two requests.

In many cases it is helpful or even necessary to design POST and PATCH idempotent for clients to expose conflicts and prevent resource duplicate (a.k.a. zombie resources) or lost updates, e.g. if same resources may be created or changed in parallel or multiple times. To design an idempotent API endpoint owners should consider to apply one of the following three patterns.

Note: While conditional key and secondary key are focused on handling concurrent requests, the idempotency key is focused on providing the exact same responses, which is even a stronger requirement than the idempotency defined above. It can be combined with the two other patterns.

To decide, which pattern is suitable for your use case, please consult the following table showing the major properties of each pattern:

Note: The patterns applicable to PATCH can be applied in the same way to PUT and DELETE providing the same properties.

If you mainly aim to support safe retries, we suggest to apply conditional key and secondary key pattern before the Idempotency Key pattern.

This example uses the conditional key pattern on a PATCH. The client reads the workflow and gets its entity tag. Then the client sends the entity tag in the if-match header.

If a different client changed the workflow first, the entity tag does not match. The server does not apply the change and returns 412:

The most important pattern to design POST idempotent for creation is to introduce a resource specific secondary key provided in the request body, to eliminate the problem of duplicate (a.k.a zombie) resources.

The secondary key is stored permanently in the resource as alternate key or combined key (if consisting of multiple properties) guarded by a uniqueness constraint enforced server-side, that is visible when reading the resource. The best and often naturally existing candidate is a unique foreign key, that points to another resource having one-on-one relationship with the newly created resource, e.g. a parent process identifier.

A good example here for a secondary key is the shopping cart ID in an order resource.

Note: When using the secondary key pattern without Idempotency-Key all subsequent retries should fail with status code 409 (conflict). We suggest to avoid 200 here unless you make sure, that the delivered resource is the original one implementing a well defined behavior. Using 204 without content would be a similar well defined option.

In this example, cartId is the secondary key of an order. The server allows only one order for each cart.

The first request creates the order:

A retry with the same cartId does not create a second order. The server returns 409:

A query or header parameter that accepts more than one value is a collection parameter. Define a collection parameter as an array, and set style and explode explicitly. Then the documentation, the SDKs and the service agree on how the client sends the values.

Use type: array with items for a collection parameter. Do not use a string parameter that holds a comma-separated list. The standard collection parameters filters and sorters (see MUST stick to conventional query parameters) are exceptions, because their values are expressions.

For a query parameter, use style: form and explode: true. The client repeats the parameter for each value. This is the OpenAPI default, and the current SailPoint APIs use it.

For a header parameter, use style: simple and explode: false. The client sends the values in one header, separated by commas. This is the only style that OpenAPI allows for headers.

If the number of values has a limit, set maxItems on the array schema. If the values come from a fixed list, set enum on the items schema.

TBD

Minimalistic query languages based on query parameters are suitable for simple use cases with a small set of available filters that are combined in one way and one way only (e.g. and semantics). Simple query languages are generally preferred over complex ones.

Some APIs will have a need for sophisticated and more complex query languages. Dominant examples are APIs around search (incl. faceting) and product catalogs.

Aspects that set those APIs apart from the rest include but are not limited to:

APIs that qualify for a specific, complex query language are encouraged to use nested JSON data structures and define them using OpenAPI directly. The provides the following benefits:

JSON-specific rules and most certainly needs to make use of the GET-with-body pattern.

Sometimes certain collection resources or queries will not list all the possible elements they have, but only those for which the current client is authorized to access.

Implicit filtering could be done on:

In such cases, the fact that implicit filtering is applied must be documented in the API specification’s endpoint description. Example:

If an employee of the company Foo accesses one of our business-to-business service and performs a GET /business-partners, it must, for legal reasons, not display any other business partner that is not owned or contractually managed by her/his company. It should never see that we are doing business also with company Bar.

Response as seen from a consumer working at FOO:

Response as seen from a consumer working at BAR:

The API Specification should then specify something like this:

APIs should define the functional, business view and abstract from implementation aspects. Success and error responses are a vital part to define how an API is used correctly.

Therefore, you must define all success and service specific error responses in your API specification. Both are part of the interface definition and provide important information for service clients to handle standard as well as exceptional situations.

Every operation must define at least these responses:

An operation with no parameters and no request body has no input that can be bad, so it does not need a 400 response. Path-level parameters count as parameters of the operation.

Each error response must use the standard error response object. See MUST use a standard error response object.

Use $ref to the shared response files in api-specs/src/main/yaml/apis/shared/responses/. Do not use the files in v3/responses/. They are deprecated. If a status code that many collections use has no shared file, add one to apis/shared/responses/.

Hint: In most cases it is not useful to document all technical errors, especially if they are not under control of the service provider. Thus unless a response code conveys application-specific functional semantics or is used in a none standard way that requires additional explanation, multiple error response specifications can be combined using the following pattern. The default response uses the standard error response object (see MUST use a standard error response object):

API designers should also think about a troubleshooting board as part of the associated online API documentation. It provides information and handling guidance on application-specific errors and is referenced via links from the API specification. This can reduce service support tasks and contribute to service client and provider performance.

All error responses must use the standard error response DTO object defined at https://github.com/sailpoint/cloud-api-client-common/blob/master/api-specs/src/main/yaml/apis/shared/schemas/errorresponsedto.yaml. This provides a consistent error response structure that can be easily consumed by clients.

An error response body then looks like this:

If using the detailCode within the https://github.com/sailpoint/cloud-api-client-common/blob/master/api-specs/src/main/yaml/apis/shared/schemas/errorresponsedto.yaml, then the service owner is free to create their own logic for detail codes that will aid them in debugging issues with the service.

In this example, the service team made the code 400.1.2 for a filter on a field that the service does not support.

Each endpoint must define a response example for every success and error response that can be returned. These examples must accurately reflect what can be returned by the endpoint. Default examples shared across multiple endpoints may be used as long as they accurately reflect what can be returned by the endpoint. If a default example doesn’t accurately reflect what can be returned by an endpoint, then that endpoint must override the default example with one that is accurate.

In this example, each response of the operation has an example that matches what the operation returns.

The shared 403 and 500 responses have examples that are accurate for this operation. So the operation uses them as they are.

You must only use standardized HTTP status codes consistently with their intended semantics. You must not invent new HTTP status codes.

RFC standards define ~60 different HTTP status codes with specific semantics (mainly RFC7231 and RFC 6585) — and there are upcoming new ones, e.g. draft legally-restricted-status. See overview on all error codes on Wikipedia or via https://httpstatuses.com/) also inculding 'unofficial codes', e.g. used by popular web servers like Nginx.

Below we list the most commonly used and best understood HTTP status codes, consistent with their semantic in the RFCs. APIs should only use these to prevent misconceptions that arise from less commonly used HTTP status codes.

Important: As long as your HTTP status code usage is well covered by the semantic defined here, you should not describe it to avoid an overload with common sense information and the risk of inconsistent definitions. Only if the HTTP status code is not in the list below or its usage requires additional information aside the well defined semantic, the API specification must provide a clear description of the HTTP status code in the response.