swagger: '2.0' info: title: Text description: > Manage localizable and customizable text strings for client applications. The Text API is a repository for customizable and localizable text strings which the financial institution may wish to customize in order to change their user experience. The primary consumer of this API is client applications. Example of customizable text includes: * page or form titles * field labels * hover tips * URLs (for images or other resources) * icon references in image icon sets * instructions or other in-line help * larger text blocks such as Markdown text blocks. The Text API manages only static text that is part of the UX or clients, not dynamic changing text _data_ (such as an banking product names, document names, description) provided by the services or the users. ## Text Strings and Text String Groups Text is organized into named _groups_ of related strings. These groups often correspond to client application features, such as banking, transfers, or digital account opening. The special group name `common` represents content that is "common" to (or shared with) all other groups. Groups names may be nested logically. For example, the group `common.fi` is for text related to the financial institution within the `common` group. Text strings may include references to other strings, including strings in other groups. For example, consider the message string `Contact {{common.fi.name}} customer support at {{common.fi.supportNumber}} or {{common.fi.supportLink_url}}` This template resolve to a string result such as `Contact 3rd Party Bank customer support at 555-555-1234 or [Support](https://www3rdparty.bank/support)` `{{common.fi.supportNumber}}` is an example of a string reference by a _key_ which consists of a group name (`common.fi`) and string name (`supportNumber`). Unresolved references are left unexpanded. For example, if there is no string named `support_url` in the `common.fi` group, the above text string request returns `Contact 3rd Party Bank customer support at 555-555-1234 or {{common.fi.supportLink_url}}` The reserved group name `_` is an alias for the current group. This allows text strings to easily reference other text strings in the group in a more concise manner. For example, if the text string `Contact {{common.fi.name}} customer support at {{common.fi.supportNumber}} or {{common.fi.supportLink_url}}` exists in the `common.fi` group, it could be coded as `Contact {{_.name}} customer support at {{_.supportNumber}} or {{_.supportLink_url}}` By convention, string references without group names (that is, those with the format `{{name}}`) are not expanded by the Text service and are left for client-side expansion using a client-supplied environment map of name/value pairs. The same is true for references {{groupId.textStringId}} where the named group or string are not defined.) Text strings are referenced by a string ID, which must be a simple name: `name = [ letter | "_" ] ( letter | digit | "_" | "$" )*`
`textStringId = name` Text string names may end with a `_` and a _suffix_ which indicates the purpose or use of the text string. The Text API supports the following suffixes: * `_label` - labels for UI fields; allows Markdown (125) * `_tip` - tool tips, hover tips; allows Markdown (250) * `_md` - Markdown formatted text blocks, such as instructions. Possibly multi-line. (4000) * `_url` - URLs of other resources, such as images. Example: `backgroundImage_url` (250) * `_help` - Short on-screen Markdown help for `(?)` or `(i)` icons or _Explain this_ buttons. (1000) The maximum length of a text string is determined by the suffix (shown in parentheses above). Client applications must render [Markdown](https://help.github.com/articles/basic-writing-and-formatting-syntax/) text values before presenting `*_label`, `*_md` and `*_help` text strings to the user. Web applications may format Markdown to HTML for example. A group ID is a simple name or `.`-separated names for two- or three-level names such as `level1.level2.level3`. `groupId = name ( "." name ) {0,2}` The concatenation of the group ID and a period and the string ID is the string's ***key***. ## Customization access controls Different text groups are customizable by different audiences. Only Apiture Engineering may customize some text groups; Only Apiture Professional Services may customize some text groups; financial institutions may customize all other text groups. ## Natural Language Support Each text string can have different natural language variants, access by a language code. For example, a text string `preferredAddressOption_label` may have values for the [RFC 3066](https://tools.ietf.org/html/rfc3066) language identifiers `es-MX`, `es-SP`, `fr`, `de`, `en-GB` and `en-US`. The client specifies the preferred language when requesting text strings and The service follows locale inheritance rules when resolving the request. (See the [ `GET /resolved` (`getResolvedText`)](#op-getresolved) operation below.) For example, when asking for resolved text for `es-MX`, if a text string `preferredAddressOption_label` is not defined for `es-MX`, the service looks for a value for `es`, and if not defined for `es`, the service returns the value defined for the default locale. The default locale is `en-US`. The default locale-independent value for each text string _must_ be defined when adding groups and text strings. ## Presentation Format/Form Factors Text also supports content that is specific to a _format_ which represents different user experience form factors. A mobile app with a smaller screen format may require a different set of labels than those used for web or larger tablets. The service will also fall back from format-specific to format-agnostic labels. The language and format are examples of optional text parameters. The client can request text either by the URL path GET `/groups/{groupId}/strings/{textStringId}` or by requesting all text strings in one or more groups via `GET /text/resolved?group=group1|group2|...|groupN` or for all groups, `GET /text/resolved`. These operations support parameterization of the response with the `format=` query parameter and/or the `?languages=` query parameter. Note that unlike many other Apiture APIs, the identifiers for groups and strings (`groupId` and `textStringId`) are _names_, not opaque resource IDs. Clients may use `PUT` to _create_ or _update_ new groups and new text strings within groups with client-supplied names rather than using `POST` to create resources and have the service generate the IDs. # Error Types Error responses in this API may have one of the `type` values described below. See [Errors](https://developer.apiture.com/docs/concepts/errors) for more information on error responses and error types. ## invalidAcceptLanguage **Description**: The `Accept-Language` request header is not well-formed.
**Remediation**: Resubmit the operation with a valid `Accept-Language` request header. ## invalidLanguageQuery **Description**: The `language` query parameter is not well-formed.
**Remediation**: Resubmit the operation with a valid `language` query parameter. ## invalidGroupQuery **Description**: The `group` query parameter is not well-formed.
**Remediation**: Resubmit the operation with a valid `group` query parameter. ## invalidFormatQuery **Description**: The `format` query parameter is not well-formed.
**Remediation**: Resubmit the operation with a valid `format` query parameter. ## missingStringItems **Description**: A request to update an existing text string omitted an previously defined item corresponding to a format and/or language.
**Remediation**: Include all original string items when updating a text string, either replacing the value, or adding new items for new formats and/or languages. The `attributes` object in the error may have the following properties: | Property | Type | Description | |----------|------|-------------| | missingItems | [object] | The existing string items (format+language) which were omitted from the request. | ## circularStringDefinition **Description**: The request would result in text string definitions with circular text string references.
**Remediation**: Avoid circular references in text string definitions. The `attributes` object in the error may have the following properties: | Property | Type | Description | |----------|------|-------------| | cycle | [object] | The cycle of text strings. | ## invalidString **Description**: A string item name is invalid.
**Remediation**: Use a string item name that matches the pattern `^[a-z][a-zA-Z0-9_$]{0,32}$`. The `attributes` object in the error may have the following properties: | Property | Type | Description | |----------|------|-------------| | name | string | The invalid string item name. | ## invalidFormat **Description**: A string item format is invalid or is not found.
**Remediation**: String items must use `format` names that match existing formats in the `getFormats` collection. Format names must use the pattern `^[a-z][a-zA-Z0-9_$]{3,11}$`. ## invalidLanguage **Description**: A string item language is invalid.
**Remediation**: String items must use [RFC 3066](https://tools.ietf.org/html/rfc3066) language identifiers that match the pattern `^[a-z]{2,3}(-[a-zA-Z0-9]{2,4})?$`. ## stringNameMismatch **Description**: The text string `name` does not match the URL path `{textStringId}`.
**Remediation**: The request body must concur with the `{textStringId}` in the URL. The `attributes` object in the error may have the following properties: | Property | Type | Description | |----------|------|-------------| | stringName | string | The `name` in the text string request body. | | stringId | string | The `{textStringId}` in the request URL. | ## missingDefaultValues **Description**: The text string's `values' must have one default item with no `language` or `format`.
**Remediation**: Provide a default value to use when the other values do not match the request language. The `attributes` object in the error may have the following properties: | Property | Type | Description | |----------|------|-------------| | stringId | string | The `{textStringId}` in the request URL. | ## duplicateStringValues **Description**: The `values` in a text string may not have duplicates for `language` and `format`.
**Remediation**: Submit `values` without duplicates. The `attributes` object in the error may have the following properties: | Property | Type | Description | |----------|------|-------------| | stringId | string | The `{textStringId}` in the request URL. | | format | string | The `format` property of the duplicated value, or `''` if format was omitted. | | language | string | The `language` property of the duplicated value, or `''` if language was omitted. | ## cannotUpdateImmutableGroup **Description**: Cannot update an immutable group.
**Remediation**: Check the group ID and the group's `immutable` property and avoid updating an immutable group. version: 0.7.2 contact: name: Apiture url: 'https://developer.apiture.com' email: api@apiture.com termsOfService: 'https://developer.apiture.com/docs/Apiture-Open-API-License-Agreement.pdf' schemes: - https basePath: /text consumes: - application/hal+json - application/json produces: - application/hal+json - application/json tags: - name: Text description: Text - name: Text String description: Text String - name: Text Group description: Group of Text Strings - name: API description: The Text API securityDefinitions: apiKey: type: apiKey name: API-Key in: header description: >- API Key based authentication. Each client must pass its private, unique API key, allocated in the developer portal, via the `API-Key: {api-key}` request header. accessToken: type: oauth2 flow: accessCode description: >- OAuth2 client access token authentication. The client authenticates against the server at `authorizationUrl`, passing the client's private `clientId` (and optional `clientSecret`) as part of this flow. The client obtains an access token from the server at `tokenUrl`. It then passes the received access token via the `Authorization: Bearer {access-token}` header in subsequent API calls. The authorization process also returns a refresh token which the client should use to renew the access token before it expires. authorizationUrl: /auth/oauth2/authorize tokenUrl: /auth/oauth2/token scopes: data/read: Read access to text admin/write: Write (update) access to text admin/delete: Delete access to text data/full: Full access to text paths: /resolved: get: description: >- Return all text groups and text strings for the specified (or default) language and the specified (or default) client format. The strings are _resolved_ by replacing string references (references have the form `{{key}}`) to other text strings with their corresponding values. This operation is the primary operation that clients use to load the text strings to present to one end user, based on that user's preferred language and their device format. operationId: getResolvedText tags: - Text parameters: - name: format description: >- Return text strings that match the named or default format (form factor). If no text for the requested format exists for a `textStringId`, the default text for that `textStringId` is returned. type: string in: query minLength: 4 maxLength: 10 pattern: '^[a-z][a-zA-Z0-9]{3,9}$' default: small - name: languages description: >- Return text strings that match the search priority of the given language tag(s). The array is ordered by highest to lowest preference. For example, for `?languages=es-MX,en-GB`, the response will include text strings based on the following search priority: `es-MX` ⇒ `es` ⇒ `en-GB` ⇒ `en` ⇒ `` (_default_)
Items are [RFC 3066](https://tools.ietf.org/html/rfc3066) language identifiers. If used, `Accept-Language` header is ignored. Language codes are case insensitive. in: query type: array collectionFormat: csv minItems: 1 maxItems: 6 items: type: string minLength: 2 maxLength: 8 format: language pattern: '^[a-z]{2,3}(-[a-zA-Z0-9]{2,4})?$' - name: Accept-Language in: header type: string description: >- An [HTTP `Accept-Language`](https://tools.ietf.org/html/rfc7231#section-5.3.5) request header which specifies one or more languages with weights. The response will include one string for each combination of group name and string name. This is ignored if `?languages=` query parameter is used. `Accept-Language` is processed in a similar way as the `language` query parameter. - name: groups description: >- Subset the response to only text in the group or groups named in this parameter. Each item in the comma-separated list is a one-, two-, or three-level group name. Group names are case sensitive. The default is `?groups=common`. Example: `&groups=common,help,features.x,feature.y` in: query type: array collectionFormat: csv minItems: 1 items: type: string minLength: 2 maxLength: 50 pattern: '^[a-z][a-zA-Z0-9_$]{0,15}(\.[a-z][a-zA-Z0-9_$]{0,15}){0,2}$' - name: since description: >- Return only text strings whose `updatedAt` time-stamp are newer than the `since` date-time. If omitted, return all text strings The value is an [RFC 3339](https://tools.ietf.org/html/rfc3339) time stamp in `YYYY-MM-DDThh:mm:ss.sssZ` format. type: string format: date-time in: query - name: resolve description: 'If `?resolve=false`, this operation does not resolve embedded `{{key}}` text string references.' type: boolean in: query default: true - name: subgroups description: >- If `true`, the response includes all subgroups of each group named in `groups`. This example may return the groups `common` and `common.fi`, `common.print`, and `web.responsive` but not the groups `commonTrust` or `helpless`. type: boolean in: query default: true - $ref: '#/parameters/ifNoneMatchHeaderParam' responses: '200': description: OK schema: $ref: '#/definitions/resolvedStrings' headers: ETag: description: >- The `ETag` response header specifies an entity tag which may be provided in an `If-Match` request header for *`PUT`* or *`PATCH`* operations which update this text format resource. type: string '202': description: >- Accepted. The request was accepted and the service is generating ghe response. The client should retry the event after a short interval until the request returns a 200 OK response. schema: $ref: '#/definitions/resolvedStrings' type: object headers: Retry-After: description: >- Indicates a suggested delay in seconds after which the client should retry the operation, until the response code is 200. Example: `Retry-After: 10` type: string '304': $ref: '#/responses/304' '400': description: |- Bad Request. One of the request parameters was not well formed. This error response may have one of the following `type` values: * [`invalidLanguageQuery`](#err-invalidLanguageQuery) * [`invalidAcceptLanguage`](#err-invalidAcceptLanguage) * [`invalidGroupQuery`](#err-invalidGroupQuery) * [`invalidFormatQuery`](#err-invalidFormatQuery) schema: $ref: '#/definitions/errorResponse' x-apiture-errors: - invalidLanguageQuery - invalidAcceptLanguage - invalidGroupQuery - invalidFormatQuery security: - apiKey: [] '/groups/{groupId}/strings': parameters: - $ref: '#/parameters/groupIdPathParam' get: summary: Return a collection of text strings description: >- Return a collection of text strings within the group. Since the number of text strings in a group is relatively small, this operation does not implement pagination, sorting, filtering, or searching. operationId: getStrings tags: - Text String parameters: - $ref: '#/parameters/ifNoneMatchHeaderParam' responses: '200': description: OK schema: $ref: '#/definitions/textStrings' headers: ETag: description: >- The `ETag` response header specifies an entity tag which may be provided in an `If-Match` request header for *`PUT`* or *`PATCH`* operations which update this text format resource. type: string '304': $ref: '#/responses/304' '422': $ref: '#/responses/422' security: - apiKey: [] '/groups/{groupId}/strings/{textStringId}': parameters: - $ref: '#/parameters/groupIdPathParam' - $ref: '#/parameters/textStringIdPathParam' get: summary: Fetch a representation of this text string description: 'Return a [HAL](http://developer.apiture.com/docs/concepts/hal) representation of this text string resource.' operationId: getString tags: - Text String parameters: - $ref: '#/parameters/ifNoneMatchHeaderParam' responses: '200': description: OK schema: $ref: '#/definitions/textString' headers: ETag: description: >- The `ETag` response header specifies an entity tag which may be provided in an `If-Match` request header for *`PUT`* or *`PATCH`* operations which update this text string resource. type: string '304': $ref: '#/responses/304' '404': $ref: '#/responses/404String' security: - apiKey: [] put: summary: Create or update a text string description: >- Create a new text with the `textStringId` name if one did not already exist, or update the properties of an existing text string. This operation is limited to administrative use. operationId: setString tags: - Text String parameters: - name: string in: body description: A text string and variants for different languages and client formats. required: true schema: $ref: '#/definitions/textString' - $ref: '#/parameters/ifMatchHeaderParam' responses: '200': description: OK schema: $ref: '#/definitions/textString' headers: ETag: description: >- The `ETag` response header specifies an entity tag which may be provided in an `If-Match` request header for *`PUT`* or *`PATCH`* operations which update this text string resource. type: string '201': description: Created. A new text string was added to the group. schema: $ref: '#/definitions/textString' headers: ETag: description: >- The `ETag` response header specifies an entity tag which may be provided in an `If-Match` request header for *`PUT`* or *`PATCH`* operations which update this text string resource. type: string Location: description: >- The URI of the new string resource. If the URI begins with / it is relative to the API root context. Else, it is a full URI starting with *`scheme`*`://host` type: string format: uri '400': $ref: '#/responses/400' '409': $ref: '#/responses/409StringConflict' '412': $ref: '#/responses/412' '422': $ref: '#/responses/422String' security: - apiKey: [] accessToken: - admin/write delete: summary: Delete this text string resource description: Delete this text string resource and any resources that are owned by it. This operation is limited to administrative use. operationId: deleteString tags: - Text String responses: '204': $ref: '#/responses/204Deleted' security: - apiKey: [] accessToken: - admin/delete parameters: [] /groups: get: summary: Return a collection of text groups description: |- Return the collection of text groups. Since the number of groups is relatively small, this operation does not implement pagination, sorting, filtering, or searching. operationId: getGroups tags: - Text Group parameters: - $ref: '#/parameters/ifNoneMatchHeaderParam' responses: '200': description: OK schema: $ref: '#/definitions/groups' headers: ETag: description: >- The `ETag` response header specifies an entity tag which may be provided in an `If-Match` request header for *`PUT`* or *`PATCH`* operations which update this text format resource. type: string '304': $ref: '#/responses/304' '400': $ref: '#/responses/400' '422': $ref: '#/responses/422Group' security: - apiKey: [] '/groups/{groupId}': parameters: - $ref: '#/parameters/groupIdPathParam' get: summary: Fetch a representation of this text group description: 'Return a [HAL](http://developer.apiture.com/docs/concepts/hal) representation of this text group resource.' operationId: getGroup tags: - Text Group parameters: - $ref: '#/parameters/ifNoneMatchHeaderParam' responses: '200': description: OK schema: $ref: '#/definitions/group' headers: ETag: description: >- The `ETag` response header specifies an entity tag which may be provided in an `If-Match` request header for *`PUT`* or *`PATCH`* operations which update this text group resource. type: string '304': $ref: '#/responses/304' '404': $ref: '#/responses/404Group' security: - apiKey: [] put: summary: Create or update a text group description: 'Create a text group, or update an existing text group''s properties.' operationId: setGroup tags: - Text Group parameters: - name: group in: body required: true schema: $ref: '#/definitions/group' - $ref: '#/parameters/ifMatchHeaderParam' responses: '200': description: OK schema: $ref: '#/definitions/group' headers: ETag: description: >- The `ETag` response header specifies an entity tag which may be provided in an `If-Match` request header for *`PUT`* or *`PATCH`* operations which update this text group resource. type: string '201': description: Created. A new text group was created. schema: $ref: '#/definitions/group' headers: ETag: description: >- The `ETag` response header specifies an entity tag which may be provided in an `If-Match` request header for *`PUT`* or *`PATCH`* operations which update this text group resource. type: string Location: description: >- The URI of the new string resource. If the URI begins with / it is relative to the API root context. Else, it is a full URI starting with *`scheme`*`://host` type: string format: uri '400': $ref: '#/responses/400' '404': $ref: '#/responses/404Group' '409': $ref: '#/responses/409Group' '412': $ref: '#/responses/412' '422': $ref: '#/responses/422' security: - apiKey: [] accessToken: - data/write delete: summary: Delete this text group resource description: Delete this text group resource and any resources that are owned by it. operationId: deleteGroup tags: - Text Group responses: '204': $ref: '#/responses/204Deleted' security: - apiKey: [] accessToken: - data/delete parameters: [] /formats: get: summary: Return a collection of text formats description: |- Return a collection of text formats. The Text service has default formats named `small` and `large`. operationId: getFormats tags: - Text Format security: - apiKey: [] parameters: - $ref: '#/parameters/ifNoneMatchHeaderParam' responses: '200': description: OK schema: $ref: '#/definitions/formats' headers: ETag: description: >- The `ETag` response header specifies an entity tag which may be provided in an `If-Match` request header for *`PUT`* or *`PATCH`* operations which update this text format resource. type: string '304': $ref: '#/responses/304' '400': $ref: '#/responses/400' '422': $ref: '#/responses/422' '/formats/{formatId}': get: summary: Fetch a representation of this text format description: 'Return a [HAL](http://developer.apiture.com/docs/concepts/hal) representation of this text format resource.' operationId: getFormat tags: - Text Format security: - apiKey: [] parameters: - $ref: '#/parameters/formatIdPathParam' - $ref: '#/parameters/ifNoneMatchHeaderParam' responses: '200': description: OK schema: $ref: '#/definitions/format' headers: ETag: description: >- The `ETag` response header specifies an entity tag which may be provided in an `If-Match` request header for *`PUT`* or *`PATCH`* operations which update this text format resource. type: string '304': $ref: '#/responses/304' '404': $ref: '#/responses/404Format' put: summary: Update or create a text format description: Perform a complete replacement of this text format. operationId: setFormat tags: - Text Format security: - apiKey: [] accessToken: - data/write parameters: - $ref: '#/parameters/formatIdPathParam' - name: format in: body required: true schema: $ref: '#/definitions/format' - $ref: '#/parameters/ifMatchHeaderParam' responses: '200': description: OK schema: $ref: '#/definitions/format' headers: ETag: description: >- The `ETag` response header specifies an entity tag which may be provided in an `If-Match` request header for *`PUT`* or *`PATCH`* operations which update this text format resource. type: string '201': description: Created. A new format was created. schema: $ref: '#/definitions/format' headers: ETag: description: >- The `ETag` response header specifies an entity tag which may be provided in an `If-Match` request header for *`PUT`* or *`PATCH`* operations which update this text format resource. type: string Location: description: >- The URI of the new string resource. If the URI begins with / it is relative to the API root context. Else, it is a full URI starting with *`scheme`*`://host` type: string format: uri '400': $ref: '#/responses/400' '404': $ref: '#/responses/404Format' '412': $ref: '#/responses/412' '422': $ref: '#/responses/422Format' /: get: summary: Top-level resources and operations in this API description: Return links to the top-level resources and operations in this API. operationId: getApi responses: '200': description: OK schema: $ref: '#/definitions/root' tags: - API security: - apiKey: [] parameters: [] /apiDoc: get: summary: Return API definition document description: Return the OpenAPI document that describes this API. operationId: getApiDoc produces: - application/json - application/openapi+json;version=2.0 - application/openapi+yaml;version=2.0 responses: '200': description: OK schema: type: object tags: - API security: - apiKey: [] parameters: [] parameters: textStringIdPathParam: name: textStringId description: The unique identifier (`name`) of this text string. in: path type: string required: true minLength: 2 maxLength: 32 pattern: '^[a-z][a-zA-Z0-9_$]{1,31}$' groupIdPathParam: name: groupId description: The unique identifier (`name`) of this text group. in: path type: string required: true minLength: 2 maxLength: 50 pattern: '^[a-z][a-zA-Z0-9_$]{0,15}(\.[a-z][a-zA-Z0-9_$]{0,15}){0,2}$' formatIdPathParam: name: formatId description: The unique identifier (`name`) of this text format. in: path type: string required: true minLength: 4 maxLength: 12 pattern: '^[a-z][a-zA-Z0-9]{3,11}$' filterQueryParam: name: filter in: query description: 'Optional filter criteria. See [filtering](http://developer.apiture.com/docs/concepts/filtering).' type: string ifMatchHeaderParam: name: If-Match description: 'The entity tag that was returned in the `ETag` response. If passed, this must match the current entity tag of the resource.' in: header type: string ifNoneMatchHeaderParam: name: If-None-Match description: >- The entity tag that was returned in the `ETag` response. If the resource's current entity tag matches, the `GET` will return 304 (Not Modified) and no response body, else the resource representation will be returned. in: header type: string responses: '304': description: Not Modified. The resource has not been modified since it was last fetched. '400': description: >- Bad Request. The request body or one or more of the query parameters was not well formed. The `_error` field in the response will contain details about the request error. schema: $ref: '#/definitions/errorResponse' '412': description: >- Precondition Failed. The supplied `if-Match` header value does not match the most recent `ETag` response header value. The resource has changed in the interim. schema: $ref: '#/definitions/errorResponse' '422': description: >- Unprocessable Entity. One or more of the query parameters was well formed but otherwise invalid. The `_error` field in the response will contain details about the request error. schema: $ref: '#/definitions/errorResponse' 404String: description: >- Not Found. There is no such text string resource at the specified `{textStringId}`. The `_error` field in the response will contain details about the request error. schema: $ref: '#/definitions/errorResponse' 404Group: description: >- Not Found. There is no such text group resource at the specified `{groupId}`. The `_error` field in the response will contain details about the request error. schema: $ref: '#/definitions/errorResponse' 409Group: description: Conflict. schema: $ref: '#/definitions/errorResponse' x-apiture-error: - cannotUpdateImmutableGroup 404Format: description: >- Not Found. There is no such text format resource at the specified `{formatId}`. The `_error` field in the response will contain details about the request error. schema: $ref: '#/definitions/errorResponse' 422String: description: |- Unprocessable Entity: When creating or updating a string, the request contains an invalid string representation. This error response may have one of the following `type` values: * [`invalidString`](#err-invalidString) * [`invalidFormat`](#err-invalidFormat) * [`invalidLanguage`](#err-invalidLanguage) * [`missingDefaultValues`](#err-missingDefaultValues) * [`stringNameMismatch`](#err-stringNameMismatch) * [`duplicateStringValues`](#err-duplicateStringValues) schema: $ref: '#/definitions/errorResponse' x-apiture-errors: - invalidString - invalidFormat - invalidLanguage - missingDefaultValues - stringNameMismatch - duplicateStringValues 422Group: description: |- Unprocessable Entity: When creating or updating a group, the request contains an invalid group definition This error response may have one of the following `type` values: * [`invalidString`](#err-invalidString) * [`invalidFormat`](#err-invalidFormat) * [`invalidLanguage`](#err-invalidLanguage) schema: $ref: '#/definitions/errorResponse' x-apiture-errors: - invalidString - invalidFormat - invalidLanguage 422Format: description: |- Unprocessable Entity: When creating or updating a string format, the request contains one or more invalid format definitions. This error response may have one of the following `type` values: * [`invalidFormat`](#err-invalidFormat) schema: $ref: '#/definitions/errorResponse' x-apiture-errors: - invalidFormat 409StringConflict: description: |- Conflict: The value contains a string reference that would result in a circular reference. This error response may have one of the following `type` values: * [`circularStringDefinition`](#err-circularStringDefinition) schema: $ref: '#/definitions/errorResponse' x-apiture-errors: - circularStringDefinition 204Deleted: description: No Content. The resource was deleted successfully. definitions: textStringFields: title: Text String Fields (v1.1.0) x-apiture-version: 1.1.0 description: 'Properties of a text string object. (This is a fragment schema, used to define other schemas.)' x-apiture-fragment: true properties: name: description: The name of this text string. The name must be unique within the group. type: string minLength: 2 maxLength: 32 pattern: '^[a-z][a-zA-Z0-9_$]{1,31}$' example: support_url values: description: String values for each combination of format and language. type: array items: $ref: '#/definitions/textStringItem' updatedAt: description: 'The date-time when this text string was last modified. This is in [RFC 3339](https://tools.ietf.org/html/rfc3339) UTC format.' type: string format: date-time example: {} readOnly: true type: object x-apiture-flattened: true textStringItem: title: Text String Item (v1.1.0) description: >- A since string value, corresponding to a `textStringId`, language code, and a format code. One or more text string items form a `textString` object with a shared `textStringId`. required: - value x-apiture-version: 1.1.0 properties: value: description: The text value of this string. type: string maxLength: 4096 language: type: string description: >- The [RFC 3066](https://tools.ietf.org/html/rfc3066) language identifier for this string item. If omitted on this instance, this is a _default_ text string item to be used if no other items match a request. Language codes are case insensitive. minLength: 2 maxLength: 8 format: language pattern: '^[a-z]{2,3}(-[a-zA-Z0-9]{2,4})?$' format: description: >- The name of a format (or form factor) of the client user experience that this string item best matches. If omitted, this is a default string item to be used if no other items match a request. If specified, this must be the ID of a format resource at `/text/formats/{formatId}`, such as `small` or `large`. type: string minLength: 4 maxLength: 12 pattern: '^[a-z][a-zA-Z0-9]{3,11}$' example: value: 'Contactez le support client {{common.fi.name}} au {{common.fi.supportNumber}} ou au {{common.fi.support_url}}' format: large language: fr type: object x-apiture-flattened: true textString: title: Text String (v1.1.0) description: > A named text string within a group. Each text string contains one or more `values`, parameterized by an optional `language` code and `format` code. Items without a `language` and `format` serve as default values which are used if no item matches the requested language and format. The text string's `values` must include exactly one default item with no `language` and `format`. No two values may have the same `format` and `language`. Response and request bodies using this textString schema may contain the following links:
RelSummaryMethod
selfFetch a representation of this text stringGET
apiture:groupFetch a representation of this text groupGET
x-apiture-version: 1.1.0 example: name: contactSupport _profile: 'https://api.apiture.com/schemas/text/textString/v1.1.0/profile.json' updatedAt: '2019-11-18T11:23:16.375Z' values: - value: 'Contact {{common.fi.name}} customer support at {{common.fi.supportNumber}} or {{common.fi.support_url}}' format: large - value: 'Contact {{common.fi.name}} support at {{common.fi.support_url}}' format: small - value: >- Póngase en contacto con el servicio de atención al cliente de {{common.fi.name}} en {{common.fi.supportNumber}} o {{common.fi.support_url}} format: large language: es - value: 'Póngase en contacto con el soporte de {{common.fi.name}} en {{common.fi.supportNumber}} o {{common.fi.support_url}}' format: small language: es - value: 'Contactez le support client {{common.fi.name}} au {{common.fi.supportNumber}} ou au {{common.fi.support_url}}' format: large language: fr - value: 'Contacter le support {{common.fi.name}} au {{common.fi.support_url}}' format: small language: fr x-apiture-links: - rel: self operationId: getString - rel: 'apiture:group' operationId: getGroup x-apiture-composition: - $ref: '#/definitions/abstractResource' - $ref: '#/definitions/textStringFields' properties: _links: description: 'An optional map of links, mapping each link relation to a link object. This model defines the `_links` object of HAL representations.' $ref: '#/definitions/links' _embedded: description: 'An optional map of nested resources, mapping each nested resource name to a nested resource representation.' type: object _profile: description: 'The URI of a [resource profile](https://developer.apiture.com/docs/concepts/profiles/) which describes the representation.' type: string format: uri _error: description: An object which describes an error. This value is omitted if the operation succeeded without error. type: object allOf: - $ref: '#/definitions/error' name: description: The name of this text string. The name must be unique within the group. type: string minLength: 2 maxLength: 32 pattern: '^[a-z][a-zA-Z0-9_$]{1,31}$' example: support_url values: description: String values for each combination of format and language. type: array items: $ref: '#/definitions/textStringItem' updatedAt: description: 'The date-time when this text string was last modified. This is in [RFC 3339](https://tools.ietf.org/html/rfc3339) UTC format.' type: string format: date-time example: {} readOnly: true type: object x-apiture-flattened: true resolvedStrings: title: Resolved Strings (v1.0.0) description: >- Resolved text string items for a specific language or set of languages and format. This contains `groups` which is a map of maps. The outer map has group names as keys and inner maps as values; the inner maps have text string names as keys and raw string values as the values. These are very light-weight representations if groups and text strings. required: - format - languages example: _profile: 'https://api.apiture.com/schemas/text/resolvedStrings/v1.1.0/profile.json' format: large languages: - en-US - en groups: common: greeting: 'Welcome, {{user.preferredName}}' common.fi: name: 3rd Party Bank supportNumber: 555-555-1234 support_url: 'https://www3rdparty.bank/support' supportLink_md: '[Support](https://www3rdparty.bank/support)' support: 'Contact 3rd Party Bank customer support at 555-555-1234 or https://www3rdparty.bank/support' help_md: 'For help, please visit [Our help page]({{common.fi.helpUrl}})' checkDeposit: title: Remote Check Deposit scanFront: Take an image of the front of the check scanBack: Take an image of the back of the check unresolvedKeys: - common.fi.helpUrl - user.preferredName x-apiture-version: 1.0.0 x-apiture-composition: - $ref: '#/definitions/abstractResource' - properties: - format - languages - groups - unresolvedKeys properties: _links: description: 'An optional map of links, mapping each link relation to a link object. This model defines the `_links` object of HAL representations.' $ref: '#/definitions/links' _embedded: description: 'An optional map of nested resources, mapping each nested resource name to a nested resource representation.' type: object _profile: description: 'The URI of a [resource profile](https://developer.apiture.com/docs/concepts/profiles/) which describes the representation.' type: string format: uri _error: description: An object which describes an error. This value is omitted if the operation succeeded without error. type: object allOf: - $ref: '#/definitions/error' format: description: The value of the `format` query parameter (or the default) used when requesting the resolved text. type: string minLength: 4 maxLength: 10 pattern: '^[a-z][a-zA-Z0-9]{3,9}$' languages: description: The language(s) from which the returned text strings are resolved. type: array items: type: string example: - es-MX - en-GB groups: description: The map of group IDs to resolved strings in that group. x-apiture-key: groupId additionalProperties: $ref: '#/definitions/resolvedGroup' unresolvedKeys: description: >- A list of string keys (`groupId` + `.` + `textStringId`) which were referenced in `groups` strings but which are not resolved either because the `groupId` was not defined, or the `textStringId` was not defined in the group named by the key. type: array items: type: string type: object x-apiture-flattened: true resolvedGroup: title: Resolved Group (v1.1.0) description: >- A resolved group of text string values for a specific language or set of languages and format. The keys in this object are group IDs such as `common`, `common.fi`, or `checkDeposit`. The values map string IDs to simple strings objects, with any resolvable text string references replaced by their values. In the example below, there is no text string `user.preferredName` so it is left unresolved. type: object x-apiture-key: textStringId x-apiture-version: 1.1.0 additionalProperties: type: string example: name: 3rd Party Bank supportNumber: 555-555-1234 support_url: 'https://www3rdparty.bank/support' supportLink_md: '[Support](https://www3rdparty.bank/support)' support: 'Contact 3rd Party Bank customer support at 555-555-1234 or https://www3rdparty.bank/support' help_md: 'For more help, please visit [Our help page](https://www3rdparty.bank/help)' properties: {} x-apiture-flattened: true textStrings: title: Text String Collection (v1.1.0) description: Collection of text strings. The items in the collection are ordered in the `_embedded.items` array; the `name` is `strings`. x-apiture-version: 1.1.0 example: _profile: 'https://api.apiture.com/schemas/text/textStrings/v1.1.0/profile.json' name: strings start: 0 limit: 2 count: 2 _links: self: href: /text/groups/common.fi/strings _embedded: items: - name: supportNumber values: - value: (910) 999-9999 format: small _profile: 'https://api.apiture.com/schemas/text/textString/v1.1.0/profile.json' _links: self: href: /text/groups/common.fi/strings/supportNumber - name: support_url values: - value: 'https://www.3rdparty.bank/support' format: small - value: 'https://www.3rdparty.bank/es/support' language: es format: small - value: 'https://www.3rdparty.bank/fr/support' language: fr format: small _profile: 'https://api.apiture.com/schemas/text/textString/v1.1.0/profile.json' _links: self: href: /text/groups/common.fi/strings/supportUrl x-apiture-composition: - $ref: '#/definitions/collection' - properties: - _embedded properties: _links: description: 'An optional map of links, mapping each link relation to a link object. This model defines the `_links` object of HAL representations.' $ref: '#/definitions/links' _embedded: type: object description: Embedded objects. properties: items: description: An array containing text string items. type: array items: $ref: '#/definitions/textString' _profile: description: 'The URI of a [resource profile](https://developer.apiture.com/docs/concepts/profiles/) which describes the representation.' type: string format: uri _error: description: An object which describes an error. This value is omitted if the operation succeeded without error. type: object allOf: - $ref: '#/definitions/error' count: description: >- The number of items in the collection. This value is _optional_ and may be omitted if the count is not computable efficiently. If a filter is applied to the collection (either implicitly or explicitly), the count, if present, indicates the number of items that satisfy the filter. type: integer start: description: The start index of this page of items. type: integer limit: description: The maximum number of items per page. type: integer name: description: The name of the collection. type: string type: object x-apiture-flattened: true group: title: Text Group (v1.0.0) description: > A text group is a named set of related text strings. Response and request bodies using this group schema may contain the following links:
RelSummaryMethod
selfFetch a representation of this text groupGET
required: - name - description example: _profile: 'https://api.apiture.com/schemas/text/group/v1.0.0/profile.json' name: common.fi description: General text which pertains to the financial institution. immutable: false updatedAt: '2019-11-18T11:23:16.375Z' _links: self: href: /text/groups/common.fi x-apiture-links: - rel: self operationId: getGroup x-apiture-version: 1.0.0 x-apiture-composition: - $ref: '#/definitions/abstractResource' - properties: - name - description - immutable - updatedAt properties: _links: description: 'An optional map of links, mapping each link relation to a link object. This model defines the `_links` object of HAL representations.' $ref: '#/definitions/links' _embedded: description: 'An optional map of nested resources, mapping each nested resource name to a nested resource representation.' type: object _profile: description: 'The URI of a [resource profile](https://developer.apiture.com/docs/concepts/profiles/) which describes the representation.' type: string format: uri _error: description: An object which describes an error. This value is omitted if the operation succeeded without error. type: object allOf: - $ref: '#/definitions/error' name: description: >- The name of this text group. This is the group ID. The name of a group is a simple identifier name such as `common` (up to 16 alphanumeric characters) or a two- or three-level name such as `common.fi` or `address.line1Label` where each level name is a simple identifier of 1 to 16 alphanumeric characters. Group names are case sensitive type: string minLength: 2 maxLength: 50 pattern: '^[a-z][a-zA-Z0-9_$]{0,15}(\.[a-z][a-zA-Z0-9_$]{0,15}){0,2}$' example: common.fi description: description: The description of this text string format. type: string minLength: 8 maxLength: 256 immutable: description: This group is immutable. type: boolean default: false example: true updatedAt: description: >- The date-time when this group (or any text strings in it) was last modified. This is in [RFC 3339](https://tools.ietf.org/html/rfc3339) UTC format. type: string format: date-time example: {} readOnly: true type: object x-apiture-flattened: true groups: title: Text Group Collection (v1.0.0) description: Collection of text groups. The items in the collection are ordered in the `_embedded.items` array; the `name` is `groups`. example: _profile: 'https://api.apiture.com/schemas/text/groups/v1.0.0/profile.json' name: groups start: 0 limit: 32 count: 32 _links: self: href: /text/groups _embedded: items: - name: common.fi description: General text which pertains to the financial institution. immutable: false updatedAt: '2019-11-18T11:23:16.375Z' _profile: 'https://api.apiture.com/schemas/text/group/v1.0.0/profile.json' _links: self: href: /text/groups/common.fi - name: help description: 'Strings that represents in-application help text, such as tool tips.' immutable: false updatedAt: '2019-11-20T12:36:02.375Z' _profile: 'https://api.apiture.com/schemas/text/group/v1.0.0/profile.json' _links: self: href: /text/groups/help x-apiture-version: 1.0.0 x-apiture-composition: - $ref: '#/definitions/collection' - properties: - _embedded properties: _links: description: 'An optional map of links, mapping each link relation to a link object. This model defines the `_links` object of HAL representations.' $ref: '#/definitions/links' _embedded: type: object description: Embedded objects. properties: items: description: An array containing text group items. type: array items: $ref: '#/definitions/group' _profile: description: 'The URI of a [resource profile](https://developer.apiture.com/docs/concepts/profiles/) which describes the representation.' type: string format: uri _error: description: An object which describes an error. This value is omitted if the operation succeeded without error. type: object allOf: - $ref: '#/definitions/error' count: description: >- The number of items in the collection. This value is _optional_ and may be omitted if the count is not computable efficiently. If a filter is applied to the collection (either implicitly or explicitly), the count, if present, indicates the number of items that satisfy the filter. type: integer start: description: The start index of this page of items. type: integer limit: description: The maximum number of items per page. type: integer name: description: The name of the collection. type: string type: object x-apiture-flattened: true format: title: Text Format (v1.0.0) description: >- Representation of text format resources. Text formats represent client-side presentation formats, such as `small` for a display with limited screen real estate, or `large` for a display with generous screen real estate. The text service supports `small` and `large`, and `small` is the default format. required: - name - description example: name: small description: 'Small or limited screen real estate, such as a hand held smartphone.' _profile: 'https://api.apiture.com/schemas/text/format/v1.0.0/profile.json' x-apiture-version: 1.0.0 x-apiture-composition: - $ref: '#/definitions/abstractResource' - properties: - name - description properties: _links: description: 'An optional map of links, mapping each link relation to a link object. This model defines the `_links` object of HAL representations.' $ref: '#/definitions/links' _embedded: description: 'An optional map of nested resources, mapping each nested resource name to a nested resource representation.' type: object _profile: description: 'The URI of a [resource profile](https://developer.apiture.com/docs/concepts/profiles/) which describes the representation.' type: string format: uri _error: description: An object which describes an error. This value is omitted if the operation succeeded without error. type: object allOf: - $ref: '#/definitions/error' name: description: 'The name of this text format. This is the format ID. Names are case sensitive. type: string' minLength: 4 maxLength: 12 pattern: '^[a-z][a-zA-Z0-9]{3,11}$' description: description: The description of this text string format. type: string minLength: 8 maxLength: 256 type: object x-apiture-flattened: true formats: title: Text Format Collection (v1.0.0) description: >- Collection of text formats. The items in the collection are ordered in the `_embedded.items` array; the `name` is `formats`. This collection is small and thus does not support pagination links. example: _profile: 'https://api.apiture.com/schemas/text/formats/v1.0.0/profile.json' name: formats start: 0 limit: 2 count: 2 _links: self: href: /text/formats _embedded: items: - name: small description: 'Small or limited screen real estate, such as a hand held smartphone.' _profile: 'https://api.apiture.com/schemas/text/format/v1.0.0/profile.json' _links: self: href: /text/formats/small - name: large description: 'A large format device with generous screen real estate, such as a desktop or laptop application or browser.' _profile: 'https://api.apiture.com/schemas/text/format/v1.0.0/profile.json' _links: self: href: /text/formats/large x-apiture-version: 1.0.0 x-apiture-composition: - $ref: '#/definitions/collection' - properties: - _embedded properties: _links: description: 'An optional map of links, mapping each link relation to a link object. This model defines the `_links` object of HAL representations.' $ref: '#/definitions/links' _embedded: type: object description: Embedded objects. properties: items: description: An array containing text format items. type: array items: $ref: '#/definitions/format' _profile: description: 'The URI of a [resource profile](https://developer.apiture.com/docs/concepts/profiles/) which describes the representation.' type: string format: uri _error: description: An object which describes an error. This value is omitted if the operation succeeded without error. type: object allOf: - $ref: '#/definitions/error' count: description: >- The number of items in the collection. This value is _optional_ and may be omitted if the count is not computable efficiently. If a filter is applied to the collection (either implicitly or explicitly), the count, if present, indicates the number of items that satisfy the filter. type: integer start: description: The start index of this page of items. type: integer limit: description: The maximum number of items per page. type: integer name: description: The name of the collection. type: string type: object x-apiture-flattened: true errorResponse: x-apiture-version: 2.0.0 title: Error Response description: 'Describes an error response, typically returned on 4xx or 5xx errors from API operations. The `_error` object contains the error details.' example: _profile: 'https://api.apiture.com/schemas/common/errorResponse/v2.0.0/profile.json' _error: _id: 2eae46e1-575c-4d69-8a8f-0a7b0115a4b3 message: The value for deposit must be greater than 0. statusCode: 422 type: positiveNumberRequired attributes: value: -125.5 remediation: Provide a value which is greater than 0 occurredAt: '2018-01-25T05:50:52.375Z' _links: describedby: href: 'https://api.apiture.com/errors/positiveNumberRequired' _embedded: errors: [] x-apiture-resolved-from: 'https://production.api.apiture.com/schemas/common/errorResponse/v2.0.0/model.json' x-apiture-namespace: common x-apiture-composition: - $ref: '#/definitions/abstractResource' properties: _links: description: 'An optional map of links, mapping each link relation to a link object. This model defines the `_links` object of HAL representations.' $ref: '#/definitions/links' _embedded: description: 'An optional map of nested resources, mapping each nested resource name to a nested resource representation.' type: object _profile: description: 'The URI of a [resource profile](https://developer.apiture.com/docs/concepts/profiles/) which describes the representation.' type: string format: uri _error: description: An object which describes an error. This value is omitted if the operation succeeded without error. type: object allOf: - $ref: '#/definitions/error' type: object x-apiture-flattened: true root: x-apiture-version: 2.0.0 title: API Root description: 'A HAL response, with hypermedia `_links` for the top-level resources and operations in API.' example: id: apiName name: API name apiVersion: 1.0.0 _profile: 'https://production.api.apiture.com/schemas/common/root/v2.0.0/profile.json' _links: {} x-apiture-resolved-from: 'https://production.api.apiture.com/schemas/common/root/v2.0.0/model.json' x-apiture-namespace: common x-apiture-composition: - $ref: '#/definitions/abstractResource' - properties: - _id - name - apiVersion properties: _links: description: 'An optional map of links, mapping each link relation to a link object. This model defines the `_links` object of HAL representations.' $ref: '#/definitions/links' _embedded: description: 'An optional map of nested resources, mapping each nested resource name to a nested resource representation.' type: object _profile: description: 'The URI of a [resource profile](https://developer.apiture.com/docs/concepts/profiles/) which describes the representation.' type: string format: uri _error: description: An object which describes an error. This value is omitted if the operation succeeded without error. type: object allOf: - $ref: '#/definitions/error' _id: description: This API's unique ID. readOnly: true type: string name: type: string description: This API's name. apiVersion: type: string description: This API's version. type: object x-apiture-flattened: true abstractResource: x-apiture-version: 2.0.0 title: Abstract Resource description: >- An abstract schema used to define other schemas for request and response bodies. This is a [HAL](https://tools.ietf.org/html/draft-kelly-json-hal-08) resource representation. This model contains hypermedia `_links`, and either optional domain object data with `_profile` and optional `_embedded` objects, or an `_error` object. In responses, if the operation was successful, this object will not include the `_error`, but if the operation was a 4xx or 5xx error, this object will not include `_embedded` or any data fields, only `_error` and optionally `_links`. example: _profile: '{uri of resource profile.json}' _links: self: href: '{uri of current resource}' x-apiture-resolved-from: 'https://production.api.apiture.com/schemas/common/abstractResource/v2.0.0/model.json' x-apiture-namespace: common x-apiture-composition: - $ref: '#/definitions/abstractRequest' - properties: - _error properties: _links: description: 'An optional map of links, mapping each link relation to a link object. This model defines the `_links` object of HAL representations.' $ref: '#/definitions/links' _embedded: description: 'An optional map of nested resources, mapping each nested resource name to a nested resource representation.' type: object _profile: description: 'The URI of a [resource profile](https://developer.apiture.com/docs/concepts/profiles/) which describes the representation.' type: string format: uri _error: description: An object which describes an error. This value is omitted if the operation succeeded without error. type: object allOf: - $ref: '#/definitions/error' type: object x-apiture-flattened: true collection: x-apiture-version: 2.0.0 title: Collection description: A collection of resources. This is an abstract model schema which is extended to define specific resource collections. x-apiture-resolved-from: 'https://production.api.apiture.com/schemas/common/collection/v2.0.0/model.json' x-apiture-namespace: common x-apiture-composition: - $ref: '#/definitions/abstractResource' - properties: - count - start - limit - name properties: _links: description: 'An optional map of links, mapping each link relation to a link object. This model defines the `_links` object of HAL representations.' $ref: '#/definitions/links' _embedded: description: 'An optional map of nested resources, mapping each nested resource name to a nested resource representation.' type: object _profile: description: 'The URI of a [resource profile](https://developer.apiture.com/docs/concepts/profiles/) which describes the representation.' type: string format: uri _error: description: An object which describes an error. This value is omitted if the operation succeeded without error. type: object allOf: - $ref: '#/definitions/error' count: description: >- The number of items in the collection. This value is _optional_ and may be omitted if the count is not computable efficiently. If a filter is applied to the collection (either implicitly or explicitly), the count, if present, indicates the number of items that satisfy the filter. type: integer start: description: The start index of this page of items. type: integer limit: description: The maximum number of items per page. type: integer name: description: The name of the collection. type: string type: object x-apiture-flattened: true abstractRequest: x-apiture-version: 2.0.0 title: Abstract Request description: >- An abstract schema used to define other request-only schemas. This is a [HAL](https://tools.ietf.org/html/draft-kelly-json-hal-08) resource representation, minus the `_error` defined in `abstractResource`. properties: _links: description: 'An optional map of links, mapping each link relation to a link object. This model defines the `_links` object of HAL representations.' $ref: '#/definitions/links' _embedded: description: 'An optional map of nested resources, mapping each nested resource name to a nested resource representation.' type: object _profile: description: 'The URI of a [resource profile](https://developer.apiture.com/docs/concepts/profiles/) which describes the representation.' type: string format: uri example: _profile: '{uri of resource profile.json}' _links: self: href: '{uri of current resource}' x-apiture-resolved-from: 'https://production.api.apiture.com/schemas/common/abstractRequest/v2.0.0/model.json' x-apiture-namespace: common type: object x-apiture-flattened: true error: x-apiture-version: 2.0.0 title: Error description: Describes an error in an API request or in a service called via the API. required: - message properties: message: type: string description: A localized message string describing the error condition. _id: description: >- A unique identifier for this error instance. This may be used as a correlation ID with the root cause error (i.e. this ID may be logged at the source of the error). This is is an opaque string. readOnly: true type: string statusCode: description: The HTTP status code associate with this error. type: integer minimum: 100 maximum: 599 example: 422 type: type: string description: >- An error identifier which indicates the category of error and associate it with API support documentation or which the UI tier can use to render an appropriate message or hint. This provides a finer level of granularity than the `statusCode`. For example, instead of just 400 Bad Request, the `type` may be much more specific. such as `integerValueNotInAllowedRange` or `numericValueExceedsMaximum` or `stringValueNotInAllowedSet`. occurredAt: type: string format: date-time description: 'An [RFC 3339](https://tools.ietf.org/html/rfc3339) UTC time stamp indicating when the error occurred.' example: '2018-02-02T03:37:15.375Z' attributes: description: >- Informative values or constraints which describe the error. For example, for a value out of range error, the attributes may specify the `minimum` and `maximum` values. This allows clients to present error messages as they see fit (the API does not assume the client/presentation tier). The set of attributes varies by error `type`. allOf: - $ref: '#/definitions/attributes' remediation: type: string description: An optional localized string which provides hints for how the user or client can resolve the error. errors: description: An optional array of nested error objects. This property is not always present. type: array items: $ref: '#/definitions/error' _links: $ref: '#/definitions/links' example: _id: 2eae46e1575c0a7b0115a4b3 message: Descriptive error message... statusCode: 422 type: errorType1 remediation: Remediation string... occurredAt: '2018-01-25T05:50:52.375Z' errors: - _id: ccdbe2c5c938a230667b3827 message: An optional embedded error - _id: dbe9088dcfe2460f229338a3 message: Another optional embedded error _links: describedby: href: 'https://developer.apiture.com/errors/errorType1' x-apiture-resolved-from: 'https://production.api.apiture.com/schemas/common/error/v2.0.0/model.json' x-apiture-namespace: common type: object x-apiture-flattened: true links: title: Links description: 'An optional map of links, mapping each link relation to a link object. This model defines the `_links` object of HAL representations.' type: object x-apiture-key: linkRelationName additionalProperties: $ref: '#/definitions/link' x-apiture-resolved-from: 'https://production.api.apiture.com/schemas/common/links/v1.0.0/model.json' x-apiture-namespace: common x-apiture-version: 1.0.0 properties: {} x-apiture-flattened: true attributes: x-apiture-version: 2.0.0 title: Attributes description: An optional map of name/value pairs which contains additional dynamic data about the resource. type: object x-apiture-key: attributeName additionalProperties: $ref: '#/definitions/attributeValue' x-apiture-resolved-from: 'https://production.api.apiture.com/schemas/common/attributes/v2.0.0/model.json' x-apiture-namespace: common properties: {} x-apiture-flattened: true link: x-apiture-version: 1.0.0 title: Link description: >- Describes a hypermedia link within a `_links` object in HAL representations. In Apiture APIs, links are [HAL links](https://developer.apiture.com/docs/concepts/links), but Apiture APIs do not use the `name` or `hreflang` properties of HAL. Apiture links _may_ include a `method` property. required: - href properties: href: type: string format: uri description: The URI or URI template for the resource/operation this link refers to. type: type: string description: The media type for the resource. templated: type: boolean description: 'If true, the link''s href is a [URI template](https://tools.ietf.org/html/rfc6570).' title: type: string description: An optional human-readable localized title for the link. deprecation: type: string format: uri description: 'If present, the containing link is deprecated and the value is a URI which provides human-readable text information about the deprecation.' profile: type: string format: uri description: 'The URI of a profile document, a JSON document which describes the target resource/operation.' example: href: /contacts/contacts/328f6bf6-d762-422f-a077-ab91ca4d0b6f title: Applicant x-apiture-resolved-from: 'https://production.api.apiture.com/schemas/common/link/v1.0.0/model.json' x-apiture-namespace: common type: object x-apiture-flattened: true attributeValue: x-apiture-version: 2.0.0 title: Attribute Value description: The data associated with this attribute. x-apiture-resolved-from: 'https://production.api.apiture.com/schemas/common/attributeValue/v2.0.0/model.json' x-apiture-namespace: common type: object properties: {} x-apiture-flattened: true x-apiture-errors: invalidAcceptLanguage: description: The `Accept-Language` request header is not well-formed. remediation: Resubmit the operation with a valid `Accept-Language` request header. invalidLanguageQuery: description: The `language` query parameter is not well-formed. remediation: Resubmit the operation with a valid `language` query parameter. invalidGroupQuery: description: The `group` query parameter is not well-formed. remediation: Resubmit the operation with a valid `group` query parameter. invalidFormatQuery: description: The `format` query parameter is not well-formed. remediation: Resubmit the operation with a valid `format` query parameter. missingStringItems: description: A request to update an existing text string omitted an previously defined item corresponding to a format and/or language. remediation: 'Include all original string items when updating a text string, either replacing the value, or adding new items for new formats and/or languages.' attributes: properties: missingItems: description: The existing string items (format+language) which were omitted from the request. type: array items: type: object properties: format: description: The string item format. type: string language: description: The string item language. type: string circularStringDefinition: description: The request would result in text string definitions with circular text string references remediation: Avoid circular references in text string definitions attributes: properties: cycle: description: The cycle of text strings. type: array items: type: object properties: string: allOf: '#/definitions/textItem' invalidString: description: A string item name is invalid. remediation: 'Use a string item name that matches the pattern `^[a-z][a-zA-Z0-9_$]{0,32}$`.' attributes: properties: name: description: The invalid string item name. type: string invalidFormat: description: A string item format is invalid or is not found. remediation: >- String items must use `format` names that match existing formats in the `getFormats` collection. Format names must use the pattern `^[a-z][a-zA-Z0-9_$]{3,11}$`. invalidLanguage: description: A string item language is invalid. remediation: >- String items must use [RFC 3066](https://tools.ietf.org/html/rfc3066) language identifiers that match the pattern `^[a-z]{2,3}(-[a-zA-Z0-9]{2,4})?$`. stringNameMismatch: description: 'The text string `name` does not match the URL path `{textStringId}`.' remediation: 'The request body must concur with the `{textStringId}` in the URL.' attributes: properties: stringName: type: string description: The `name` in the text string request body. stringId: type: string description: 'The `{textStringId}` in the request URL.' missingDefaultValues: description: The text string's `values' must have one default item with no `language` or `format`. remediation: Provide a default value to use when the other values do not match the request language. attributes: properties: stringId: type: string description: 'The `{textStringId}` in the request URL.' duplicateStringValues: description: The `values` in a text string may not have duplicates for `language` and `format`. remediation: Submit `values` without duplicates. attributes: properties: stringId: type: string description: 'The `{textStringId}` in the request URL.' format: type: string description: 'The `format` property of the duplicated value, or `''''` if format was omitted.' language: type: string description: 'The `language` property of the duplicated value, or `''''` if language was omitted.' cannotUpdateImmutableGroup: description: Cannot update an immutable group. remediation: Check the group ID and the group's `immutable` property and avoid updating an immutable group. x-apiture-traits: - api: title: Text basePath: text applied: true links: - getApi - getApiDoc - getFormats - getGroups - getResolvedText - resource: name: text group resource: group collection: groups description: A group of related text strings simpleModelSchema: true sortable: false filterable: false paginated: false searchable: false applied: true excludeMethods: - post - patch - resource: name: text string resource: string collection: strings description: A text string simpleModelSchema: true pathPrefix: '/groups/{groupId}' sortable: false filterable: false paginated: false searchable: false excludeMethods: - post - patch applied: true - resource: name: text format resource: format collection: formats description: A client format or form factor simpleModelSchema: true sortable: false filterable: false paginated: false searchable: false excludeMethods: - delete - patch - security: baseScope: data applied: true x-apiture-annotated-at: '2020-05-28T16:36:46.257Z' host: api.devbank.apiture.com