{ "swagger": "2.0", "info": { "title": "Contacts", "description": "Contacts manages contact information for people within the Apiture Banking APIs.", "version": "0.2.0", "contact": { "name": "Apiture", "url": "https://developer.apiture.com", "email": "api@apiture.com" }, "termsOfService": "TODO: Terms of Service is TBD; need input from Legal team." }, "schemes": [ "https" ], "basePath": "/contacts", "consumes": [ "application/hal+json", "application/json" ], "produces": [ "application/hal+json", "application/json" ], "tags": [ { "name": "API", "description": "Endpoints which describe this API." }, { "name": "Contact", "description": "Contact data for individuals." } ], "paths": { "/contacts": { "get": { "summary": "Return a collection of contacts", "description": "Return a [paginated](https://developer.apiture.com/docs/concepts/pagination) [sortable](https://developer.apiture.com/docs/concepts/sorting) [filterable](https://developer.apiture.com/docs/concepts/filtering) [searchable](https://developer.apiture.com/docs/concepts/searching) collection of contacts. The [links](https://developer.apiture.com/docs/concepts/links) in the response include pagination links.", "operationId": "getContacts", "x-apiture-implemented": true, "tags": [ "Contact" ], "parameters": [ { "name": "start", "in": "query", "description": "The zero-based index of the first contact item to include in this page. The default 0 denotes the beginning of the collection.", "type": "integer", "format": "int64", "default": 0 }, { "name": "limit", "in": "query", "description": "The maximum number of contact representations to return in this page.", "type": "integer", "format": "int32", "default": 100 }, { "name": "sortBy", "in": "query", "type": "string", "description": "Optional sort criteria. See [sort criteria format](https://developer.apiture.com/docs/concepts/sorting), such as `?sortBy=field1,-field2`." }, { "$ref": "#/parameters/filterQueryParam" }, { "$ref": "#/parameters/qQueryParam" } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/contacts" } }, "400": { "$ref": "#/responses/400" }, "422": { "$ref": "#/responses/422" } } }, "post": { "summary": "Create a new contact", "description": "Create a new contact in the contacts collection. ", "operationId": "createContact", "x-apiture-implemented": true, "tags": [ "Contact" ], "parameters": [ { "name": "contact", "in": "body", "description": "The data necessary to create a new contact.", "required": true, "schema": { "$ref": "#/definitions/createContact" } } ], "responses": { "201": { "description": "Created", "schema": { "$ref": "#/definitions/contact" }, "headers": { "Location": { "description": "The URI of the new 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" }, "ETag": { "description": "The `ETag` response header specifies an entity tag which must be provided in an `If-Match` request header for *`PUT`* or *`PATCH`* operations which update the resource.", "type": "string" } } }, "400": { "$ref": "#/responses/400" } } } }, "/contacts/{contactId}": { "get": { "summary": "Fetch a representation of this contact", "description": "Return a [HAL](https://developer.apiture.com/docs/concepts/hal) representation of this contact resource.", "operationId": "getContact", "x-apiture-implemented": true, "tags": [ "Contact" ], "parameters": [ { "$ref": "#/parameters/contactIdPathParam" }, { "$ref": "#/parameters/ifNoneMatchHeaderParam" } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/contact" }, "headers": { "ETag": { "description": "The `ETag` response header specifies an entity tag which must be provided in an `If-Match` request header for *`PUT`* or *`PATCH`* operations which update this contact resource.", "type": "string" } } }, "304": { "$ref": "#/responses/304" }, "404": { "$ref": "#/responses/404Contact" } } }, "put": { "summary": "Update this contact", "description": "Perform a complete replacement of this contact.", "operationId": "updateContact", "x-apiture-implemented": true, "tags": [ "Contact" ], "parameters": [ { "$ref": "#/parameters/contactIdPathParam" }, { "name": "contact", "in": "body", "required": true, "schema": { "$ref": "#/definitions/updateContact" } }, { "$ref": "#/parameters/ifMatchHeaderParam" } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/contact" }, "headers": { "ETag": { "description": "The `ETag` response header specifies an entity tag which must be provided in an `If-Match` request header for *`PUT`* or *`PATCH`* operations which update this contact resource.", "type": "string" } } }, "400": { "$ref": "#/responses/400" }, "404": { "$ref": "#/responses/404Contact" }, "412": { "$ref": "#/responses/412" }, "422": { "$ref": "#/responses/422" }, "428": { "$ref": "#/responses/428" } } }, "patch": { "summary": "Update this contact", "description": "Perform a partial update of this contact. Fields which are omitted are not updated. Nested `_embedded` and `_links` are ignored if included.", "operationId": "patchContact", "x-apiture-implemented": true, "tags": [ "Contact" ], "parameters": [ { "$ref": "#/parameters/contactIdPathParam" }, { "name": "contact", "in": "body", "required": true, "schema": { "$ref": "#/definitions/updateContact" } }, { "$ref": "#/parameters/ifMatchHeaderParam" } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/contact" }, "headers": { "ETag": { "description": "The `ETag` response header specifies an entity tag which must be provided in an `If-Match` request header for *`PUT`* or *`PATCH`* operations which update this contact resource.", "type": "string" } } }, "400": { "$ref": "#/responses/400" }, "404": { "$ref": "#/responses/404Contact" }, "412": { "$ref": "#/responses/412" }, "422": { "$ref": "#/responses/422" }, "428": { "$ref": "#/responses/428" } } } }, "/": { "get": { "summary": "Top-level resources and operations in this API", "description": "Return links to the top-level resources and operations in this API. This API provides the following links in the `_links` object:\n * **`apiture:contacts`** -- links to the `contacts` collection\n * **`apiture:createContact`** -- links to a POST operation to create a new contact", "operationId": "getApi", "x-apiture-implemented": true, "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/root" } } }, "tags": [ "API" ] } }, "/apiDoc": { "get": { "summary": "Return API definition document", "description": "Return the OpenAPI document that describes this API.", "operationId": "getApiDoc", "x-apiture-implemented": true, "produces": [ "application/json", "application/openapi+json;version=2.0", "application/openapi+yaml;version=2.0" ], "responses": { "200": { "description": "OK", "schema": { "type": "object" } } }, "tags": [ "API" ] } }, "/activeContacts": { "post": { "summary": "Activate a contact.", "tags": [ "Contact" ], "description": "Activate a contact from an inactive state.
This operation is invoked from the `apiture:activate` link on a contact resource when that contact is eligible to be activated. This operation is only allowed if the state is `inactive`.
This changes the `state` to `active`.", "operationId": "activateContact", "x-apiture-implemented": true, "parameters": [ { "$ref": "#/parameters/contactQueryParam" }, { "name": "contactUri", "description": "The URI of an existing contact which is eligible to be activated. This parameter is **deprecated**. Use the `?contact=` query parameter instead.", "type": "string", "in": "query" }, { "$ref": "#/parameters/ifMatchHeaderParam" } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/contact" }, "headers": { "ETag": { "description": "The `ETag` response header specifies an entity tag which must be provided in an `If-Match` request header for *`PUT`* or *`PATCH`* operations which update this contact resource.", "type": "string" } } }, "400": { "$ref": "#/responses/400Contact" }, "409": { "$ref": "#/responses/409ContactConflict" }, "422": { "$ref": "#/responses/422" }, "428": { "$ref": "#/responses/428" } } } }, "/inactiveContacts": { "post": { "summary": "Deactivate a contact.", "tags": [ "Contact" ], "description": "Deactivate a contact from an active state.
This operation is invoked from the `apiture:deactivate` link on a contact resource when that contact is eligible to be deactivated. This operation is only allowed if the state is `active`.
This changes the `state` to `inactive`.", "operationId": "deactivateContact", "x-apiture-implemented": true, "parameters": [ { "$ref": "#/parameters/contactQueryParam" }, { "name": "contactUri", "description": "The URI of an existing contact which is eligible to be activated. This parameter is **deprecated**. Use the `?contact=` query parameter instead.", "type": "string", "in": "query" }, { "$ref": "#/parameters/ifMatchHeaderParam" } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/contact" }, "headers": { "ETag": { "description": "The `ETag` response header specifies an entity tag which must be provided in an `If-Match` request header for *`PUT`* or *`PATCH`* operations which update this contact resource.", "type": "string" } } }, "400": { "$ref": "#/responses/400Contact" }, "409": { "$ref": "#/responses/409ContactConflict" }, "422": { "$ref": "#/responses/422" }, "428": { "$ref": "#/responses/428" } } } }, "/removedContacts": { "post": { "summary": "Remove a contact.", "tags": [ "Contact" ], "description": "Remove a contact by setting its state to `removed`.
This operation is invoked from the `apiture:remove` link on a contact resource when that contact is eligible to be removed. The contact must not be in use (there may not be any active associations to the contact.) This operation is only allowed if the state is `inactive`.
This changes the `state` to `removed`.", "operationId": "removeContact", "x-apiture-implemented": true, "parameters": [ { "$ref": "#/parameters/contactQueryParam" }, { "name": "contactUri", "description": "The URI of an existing contact which is eligible to be activated. This parameter is **deprecated**. Use the `?contact=` query parameter instead.", "type": "string", "in": "query" }, { "$ref": "#/parameters/ifMatchHeaderParam" } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/contact" }, "headers": { "ETag": { "description": "The `ETag` response header specifies an entity tag which must be provided in an `If-Match` request header for *`PUT`* or *`PATCH`* operations which update this contact resource.", "type": "string" } } }, "400": { "$ref": "#/responses/400Contact" }, "409": { "$ref": "#/responses/409ContactConflict" }, "422": { "$ref": "#/responses/422" }, "428": { "$ref": "#/responses/428" } } } } }, "parameters": { "contactIdPathParam": { "name": "contactId", "description": "The unique identifier of this contact. This is an opaque string.", "in": "path", "type": "string", "required": true }, "contactQueryParam": { "name": "contact", "description": "A string which identifies an existing contact to activate, deactivate, or remove by `POST`ing it to the corresponding resource set. The server supplies this value in a link within the representation of a contact. The value may be a `{contactId}` or a contact URI.", "type": "string", "in": "query", "required": true }, "filterQueryParam": { "name": "filter", "in": "query", "description": "Optional filter criteria. See [filtering](https://developer.apiture.com/docs/concepts/filtering).", "type": "string" }, "qQueryParam": { "name": "q", "in": "query", "description": "Optional search string. See [searching](https://developer.apiture.com/docs/concepts/searching).", "type": "string" }, "ifMatchHeaderParam": { "name": "If-Match", "description": "The entity tag that was returned in the `ETag` response. 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" } }, "428": { "description": "Precondition Required. The request did not include the required `if-Match` header. Resubmit with the operation, supplying the value of the `ETag` and the most recent state of the resource.", "schema": { "$ref": "#/definitions/errorResponse" } }, "400Contact": { "description": "Bad Request. The `contact` or `contactUri` was malformed or does not refer to a contact.", "schema": { "$ref": "#/definitions/errorResponse" } }, "404Contact": { "description": "Not Found. There is no such contact resource at the specified `{contactId}`. The `_error` field in the response will contain details about the request error.", "schema": { "$ref": "#/definitions/errorResponse" } }, "409ContactConflict": { "description": "Conflict. There is no such contact resource at the specified `{contactId}`. The `_error` field in the response will contain details about the request error. Conflict. There is a conflict between the request and the current state of the resource. It may be one of the following:\n * A contact with the associated taxId already exists\n * The `state` of a `removed` contact may not be changed.\n * The `state` of an `active` contact may not be changed to `removed`.\n * The `state` cannot be updated via a `PUT` or `POST` request. Please use the appropriate endpoint to change the state.\n * Some key fields of the contact record may not be changed or\n removed, such as their `taxId`", "schema": { "$ref": "#/definitions/errorResponse" } } }, "definitions": { "contactFields": { "title": "Contact Fields", "description": "Common fields of the contact resource used to build other model schemas.", "properties": { "firstName": { "description": "The contact's first name (or given name)", "type": "string" }, "middleName": { "description": "The contact's middle name", "type": "string" }, "lastName": { "description": "The contact's last name (or surname)", "type": "string" }, "preferredName": { "description": "The contact's preferred name. This is how the contact's name is presented to the user in the interface. The default is the contact's `firstName`.", "type": "string" }, "identification": { "description": "A collection of official identifying information associated with the contact. This currently only supports government tax ID.", "type": "array", "items": { "type": "object", "required": [ "type", "value" ], "properties": { "value": { "description": "The value of this form of identification (the tax ID as a string, for example)", "type": "string" }, "type": { "description": "The type of this form of identification. Supported types include taxId and passportNumber.", "type": "string", "enum": [ "taxId", "passportNumber" ] }, "expiration": { "description": "The date when the form of identification expires.", "type": "string", "format": "date" } } } }, "addresses": { "description": "An array of postal mailing addresses for this contact.", "type": "array", "items": { "type": "object", "$ref": "#/definitions/address" } }, "yearsAtAddress": { "description": "The contact's years at current home address", "type": "string" }, "mailingDifferentAddress": { "description": "The contact is handling a different address for mailing", "type": "boolean" }, "phones": { "description": "A collection of phone numbers associated with the contact.", "type": "array", "items": { "type": "object", "properties": { "type": { "description": "The type of phone number this represents.", "type": "string", "enum": [ "home", "work", "mobile", "other" ] }, "number": { "description": "The phone number, as a string.", "type": "string", "example": "555-555-5555" } } } }, "emailAddresses": { "description": "An array of email addresses associated with the contact. The first item, if present, is the default (preferred) contact email.", "type": "array", "items": { "type": "string", "format": "email" } }, "kycAnswers": { "description": "An object that contains the answers to kyc questions. These will be toggle-able and configurable in the future.", "type": "object" }, "birthdate": { "description": "The contact's birth date in `YYYY-MM-DD` format.", "type": "string", "format": "date" }, "citizenship": { "description": "The contact's citizenship or nationality status.", "type": "array", "items": { "type": "object", "required": [ "countryCode", "state" ], "properties": { "countryCode": { "description": "The ISO 3166-1 country code for the contact's citizenship.", "type": "string", "minLength": 2, "maxLength": 2 }, "state": { "description": "The contact's citizenship status (values TBD).", "type": "string", "enum": [ "citizen", "other" ] } } } }, "occupation": { "type": "string" }, "state": { "description": "The state of this contact.", "type": "string", "enum": [ "inactive", "active", "merged", "removed" ] } }, "example": { "firstName": "John", "middleName": "Daniel", "lastName": "Smith", "preferredName": "John", "identification": [ { "value": "111-11-1111", "type": "taxId" } ], "emailAddresses": [ "api@apiture.com", "support@apiture.com" ], "phones": [ { "type": "home", "number": "(555) 555-5555" }, { "type": "mobile", "number": "(999) 555-5555" } ], "birthdate": "1974-10-27", "citizenship": [ { "countryCode": "US", "status": "citizen" } ], "occupation": "Software Engineer", "addresses": [ { "type": "home", "addressLine1": "555 N Front Street", "addressLine2": "Suite 5555", "city": "Wilmington", "regionCode": "NC", "postalCode": "28401-5405", "countryCode": "US" }, { "type": "work", "addressLine1": "123 S 3rd Street", "addressLine2": "Apt 42", "city": "Wilmington", "regionCode": "NC", "postalCode": "28411-5405", "countryCode": "US" } ], "yearsAtAddress": 3, "mailingDifferentAddress": false, "kycAnswers": { "citizen": true, "permanentResident": true, "w9Withholdings": false, "employmentStatus": "employed", "occupation": "Software Engineer", "foreignPoliticalFigure": false, "countryPoliticalFigure": "N/A", "familyOfPoliticalFigure": false }, "state": "active" } }, "address": { "title": "Address", "description": "A postal address.", "type": "object", "properties": { "type": { "type": "string", "enum": [ "home", "work", "school", "other" ] }, "label": { "description": "A text label, suitable for presentation to the end user. This is also used if `type` is `other`.", "type": "string" }, "addressLine1": { "description": "The first street address line of the address, normally a house number and street name.", "type": "string" }, "addressLine2": { "description": "The optional second street address line of the address.", "type": "string" }, "city": { "description": "The name of the city or municipality.", "type": "string" }, "regionCode": { "description": "The mailing address region code, such as state in the US, or a province in Canada.", "type": "string", "example": "NC" }, "postalCode": { "description": "The mailing address postal code, such as a US Zip or Zip+4 code, or a Canadian postal code.", "type": "string", "example": "28401-5405" }, "countryCode": { "description": "The ISO 3166-1 country code.", "type": "string", "minLength": 2, "maxLength": 2 }, "addressId": { "description": "Identifier for address in finxact" } }, "example": { "type": "home", "addressLine1": "555 N Front Street", "addressLine2": "Suite 5555", "city": "Wilmington", "regionCode": "NC", "postalCode": "28401-5405", "countryCode": "US" } }, "createContact": { "title": "Create Contact", "description": "Representation used to create a new contact.", "required": [ "lastName" ], "allOf": [ { "$ref": "#/definitions/abstractResource" }, { "$ref": "#/definitions/contactFields" }, { "type": "object", "properties": { "attributes": { "type": "object", "description": "An optional map of name/value pairs which provide additional metadata about the contact." } } } ], "example": { "_profile": "http://api.apiture.com/schemas/basePath/contact/v1.0.0/profile.json" } }, "summaryContact": { "title": "Contact Summary", "description": "Summary representation of a contact resource in contacts collections. This representation normally does not contain any `_embedded` objects. If needed, call the `GET` operation on the item's `self` link to get `_embedded` objects.", "allOf": [ { "$ref": "#/definitions/abstractResource" }, { "$ref": "#/definitions/contactFields" }, { "type": "object", "properties": { "_id": { "description": "The unique identifier for this contact resource. This is an immutable opaque string.", "type": "string" } } } ], "example": { "_id": "0399abed-fd3d-4830-a88b-30f38b8a365c", "_profile": "http://api.apiture.com/schemas/contacts/contact/v1.0.0/profile.json", "_links": { "self": { "href": "/contacts/contacts/0399abed-fd3d-4830-a88b-30f38b8a365c" } } } }, "updateContact": { "title": "Update Contact", "description": "Representation used to update or patch a contact.", "allOf": [ { "$ref": "#/definitions/summaryContact" }, { "type": "object", "properties": { "attributes": { "type": "object", "description": "An optional map of name/value pairs which provide additional metadata about the contact." } } } ], "example": { "_id": "0399abed-fd3d-4830-a88b-30f38b8a365c", "_profile": "http://api.apiture.com/schemas/contacts/contact/v1.0.0/profile.json" } }, "contact": { "title": "Contact", "description": "Representation of a contact resource. Contact data (mailing addresses, phone numbers, email addresses) for an individual.", "allOf": [ { "$ref": "#/definitions/updateContact" }, { "type": "object", "properties": { "createdAt": { "description": "The date-time when the contact was created.", "type": "string", "format": "date-time" }, "updatedAt": { "description": "The date-time when the contact was updated", "type": "string", "format": "date-time" } } } ], "example": { "_id": "0399abed-fd3d-4830-a88b-30f38b8a365c", "_profile": "http://api.apiture.com/schemas/contacts/contact/v0.1.0/profile.json", "createdAt": "2018-04-17T10:04:46.375Z", "updatedAt": "2018-04-17T10:12:58.375Z", "_links": { "self": { "href": "/contacts/contacts/0399abed-fd3d-4830-a88b-30f38b8a365c" }, "apiture:deactivate": { "href": "/contacts/inactiveContacts?contact=0399abed-fd3d-4830-a88b-30f38b8a365c" } }, "_embedded": {} } }, "contacts": { "title": "Contact Collection", "description": "Collection of contacts. The items in the collection are ordered in the `_embedded.items` array; the `name` is `contacts`.\n The top-level `_links` object may contain pagination links (`self`, `next`, `prev`, `first`, `last`, `collection`.)", "allOf": [ { "$ref": "#/definitions/collection" }, { "type": "object", "properties": { "_embedded": { "type": "object", "properties": { "items": { "description": "An array containing a page of contact items.", "type": "array", "items": { "$ref": "#/definitions/summaryContact" } } } } } } ], "example": { "_profile": "http://api.apiture.com/schemas/contacts/contacts/v0.1.0/profile.json", "start": 10, "limit": 10, "count": 67, "name": "contacts", "_links": { "self": { "href": "/contacts/contacts?start=10&limit=10" }, "first": { "href": "/contacts/contacts?start=0&limit=10" }, "next": { "href": "/contacts/contacts?start=20&limit=10" }, "collection": { "href": "/contacts/contacts" } }, "_embedded": { "items": [ { "_id": "0399abed-fd3d-4830-a88b-30f38b8a365c", "_profile": "http://api.apiture.com/schemas/contacts/contact/v0.1.0/profile.json", "_links": { "self": { "href": "/contacts/contacts/0399abed-fd3d-4830-a88b-30f38b8a365c" } }, "firstName": "John", "middleName": "Daniel", "lastName": "Smith", "preferredName": "John", "identification": [ { "value": "111-11-1111", "type": "taxId" } ], "emailAddresses": [ "api@apiture.com", "support@apiture.com" ], "phones": [ { "type": "home", "number": "(555) 555-5555" }, { "type": "mobile", "number": "(999) 555-5555" } ], "birthdate": "1974-10-27", "citizenship": [ { "countryCode": "US", "status": "citizen" } ], "occupation": "Software Engineer", "addresses": [ { "type": "home", "addressLine1": "555 N Front Street", "addressLine2": "Suite 5555", "city": "Wilmington", "regionCode": "NC", "postalCode": "28401-5405", "countryCode": "US" }, { "type": "work", "addressLine1": "123 S 3rd Street", "addressLine2": "Apt 42", "city": "Wilmington", "regionCode": "NC", "postalCode": "28411-5405", "countryCode": "US" } ], "yearsAtAddress": 3, "mailingDifferentAddress": false, "kycAnswers": { "citizen": true, "permanentResident": true, "w9Withholdings": false, "employmentStatus": "employed", "occupation": "Software Engineer", "foreignPoliticalFigure": false, "countryPoliticalFigure": "N/A", "familyOfPoliticalFigure": false }, "state": "active" } ] } } }, "abstractResource": { "x-apiture-version": "1.0.0", "title": "Abstract Resource", "description": "An augmented [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": "http://api.apiture.com/schema/example/v1.0.0/profile.json", "_links": { "self": { "href": "{uri of current resource}" } } }, "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.", "type": "object", "additionalProperties": { "$ref": "#/definitions/link" } }, "_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" } ] } } }, "root": { "x-apiture-version": "1.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://api.apiture.com/schemas/common/root/v1.0.0/profile.json", "_links": {} }, "allOf": [ { "$ref": "#/definitions/abstractResource" }, { "type": "object", "properties": { "_id": { "type": "string", "description": "This API's unique ID." }, "name": { "type": "string", "description": "This API's name." }, "apiVersion": { "type": "string", "description": "This API's version." } } } ] }, "errorResponse": { "x-apiture-version": "1.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.", "allOf": [ { "$ref": "#/definitions/abstractResource" } ], "example": { "_profile": "http://api.apiture.com/schemas/error/v1.0.0/profile.json", "_error": { "_id": "2eae46e1-575c-4d69-8a8f-0a7b0115a4b3", "_profile": "https://api.apiture.com/schemas/error/v1.0.0/profile.json", "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": "http://doc.apiture.com/errors/positiveNumberRequired" } }, "_embedded": { "errors": [] } } } }, "error": { "x-apiture-version": "1.0.0", "title": "Error", "description": "An error description. Nested source errors are contained in the `_embedded` object with the key `\"errors\"`; this is an array of nested error objects. For example, an API which validates its request body may find multiple errors in the request, which may be detailed here. The `_links` may contain a `describedby` link which refers to a web page with details about the error. The `attributes` field An optional map of name/value pairs which provide structured data about the error. For example, if the error is a value out of range, the attributes may specify the range values `min` and `max`. This allows clients to present error messages as they see fit (the API does not assume the client/presentation tier).", "required": [ "message" ], "properties": { "message": { "type": "string", "description": "A localized message string describing the error condition." }, "_id": { "type": "string", "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." }, "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 ISO 8601 UTC time stamp indicating when the error occurred.", "example": "2018-02-02T03:37:15.375Z" }, "attributes": { "description": "Data attribute associated with the error, such as values or constraints.", "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." }, "_embedded": { "description": "Optional embedded array of errors. This field may not exist if the error does not have nested errors.", "type": "object", "properties": { "items": { "description": "An array of error objects.", "type": "array", "items": { "$ref": "#/definitions/errorResponse" } } } } }, "example": { "_id": "2eae46e1-575c-4d69-8a8f-0a7b0115a4b3", "_profile": "https://api.apiture.com/schemas/error/v1.0.0/profile.json", "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": "http://doc.apiture.com/errors/positiveNumberRequired" } }, "_embedded": { "errors": [] } } }, "attributes": { "x-apiture-version": "1.0.0", "title": "Attributes", "description": "An optional map of name/value pairs which contains additional dynamic data about the resource.", "type": "object" }, "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://tools.ietf.org/html/draft-kelly-json-hal-08#section-5), 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." } } }, "collection": { "x-apiture-version": "1.0.0", "title": "Collection", "description": "A collection of resources. This is an abstract model schema which is extended to define specific resource collections.", "allOf": [ { "$ref": "#/definitions/abstractResource" }, { "type": "object", "properties": { "count": { "description": "The number of items in the full collection.", "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" } } } ] } }, "x-apiture-errors": { "accessDenied": { "description": "The credentials supplied in the request are insufficient to grant access", "remediation": "Check the supplied credentials for validity" } }, "x-apiture-traits": [ { "api": { "title": "Contacts", "basePath": "contacts", "links": [ "getContacts", "createContact", "getApi", "getApiDoc" ] } }, { "resource": { "name": "contact", "description": "Contact data (mailing addresses, phone numbers, email addresses) for an individual.", "excludeMethods": [ "delete" ] } } ] }