x-note: DO NOT EDIT THIS GENERATED FILE. Edit source file src/openapi/openapi.yaml
x-note-generated-by: openapi-schema-resolver
x-note-generated-on: '2020-05-19T17:07:24-0400'
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 following `type` values.
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.
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 | array | 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 | array | 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. |
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.1
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: 10
pattern: '^[a-z][a-zA-Z0-9]{3,9}$'
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`.
Links
Response and request bodies using this textString
schema may contain
the following links:
Rel | Summary | Method |
self | Fetch a representation of this text
string | GET |
apiture:group | Fetch a representation of this text
group | GET |
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.
Links
Response and request bodies using this group
schema may contain
the following links:
Rel | Summary | Method |
self | Fetch a representation of this text
group | GET |
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-21T14:05:07.859Z'
host: api.devbank.apiture.com