Responses

The Xpress Insight API provides responses using the HTTP protocol.

Status Codes

The API uses standard HTTP status codes from RFC-7231 and RFC-4918 to indicate success or failure of a request; success is indicated by a status code in the 2xx range and failure is indicated by a status code in the 4xx or 5xx range.

Timestamps

Timestamps are in ISO-8601 format in accordance with RFC-3339 and are in Coordinated Universal Time (UTC), for example "2021-01-01T10:32:41.266Z".

Pagination

The API uses pagination for collection-type responses in order to provide flexibility for clients and prevent unnecessary work for the server. Paginated responses are in the form of a page structure containing a subset of the requested resource and information which the client can use to navigate through the entire collection. When paging through collections, clients indicate desired paging properties via request parameters, shown in the following table.


Parameter Name	Description
page	Integer. The number of the page to fetch, starting at 0.
size	Integer. The number of items in the page the client wishes to fetch (minimum 1).

Clients should obey the pagination details in the response, as these may differ from the requested details (for example if the client asks for a page size which is too large).

Tracing

The API supports the OpenTracing standard used for trace context propagation. Responses contain tracing information using the set of standard B3 headers (X-B3-TraceId, X-B3-ParentSpanId, X-B3-SpanId, and X-B3-Sampled).

Preferences

The API supports the following optional preferences via the standard Prefer HTTP request header:

return=minimal - the client wishes the server to return a minimal response to a successful request
return=representation - the client wishes the server to return the current state of the resource in response to a successful request (default behaviour).

The following example demonstrates how to request a minimal response when submitting a compute job:

POST /api/compute-jobs HTTP/1.1
Host: <INSIGHTURL>
Content-Type: application/vnd.com.fico.xpress.insight.v2+json
Accept: application/vnd.com.fico.xpress.insight.v2+json
Prefer: return=minimal
{...}

A typical server response is shown below:

HTTP/1.1 201 Created
Location: https://<INSIGHTURL>/api/compute-jobs/123
Content-Type: application/vnd.com.fico.xpress.insight.v2+json
Preference-Applied: return=minimal

Note: RFC-7240 specifies that a requested preference might not be applied by the server, so clients should be tolerant.

Error Handling

If an error occurs, the server responds with a standard HTTP error code in the 4xx or 5xx range, as well as a JSON object that contains error information where this is possible; in some circumstances the server cannot provide this additional information, for example when the client has requested an invalid response content type. Detailed examples of common errors can be found in the API reference documentation.

For example, if a client submitted a Mosel compute job but incorrectly provided solver options in the request, the server would respond with a 422 Unprocessable Entity response status with an accompanying error in the format below. The client could then use the details provided to perform some further actions, such as displaying information to the end user.

{
  "error": {
    "code": "FICO-Platform-Http-422",
    "timestamp": "2021-01-01T12:34:56.789Z",
    "desc": "Unprocessable Entity",
    "message": "Validation failed",
    "details": [
      {
        "code": "FICO-Platform-Http-422",
        "timestamp": "2021-01-01T12:34:56.789Z",
        "desc": "Unprocessable Entity",
        "target": null,
        "message": "Solver options are not supported for Mosel jobs"
      }
    ],
    "innerError": null,
    "traceId": "6155b2579dd6935eef68ee3748bf54a2",
    "spanId": "ef68ee3748bf54a2",
    "parentId": null
  }
}

© 2001-2024 Fair Isaac Corporation. All rights reserved. This documentation is the property of Fair Isaac Corporation (“FICO”). Receipt or possession of this documentation does not convey rights to disclose, reproduce, make derivative works, use, or allow others to use it except solely for internal evaluation purposes to determine whether to purchase a license to the software described in this documentation, or as otherwise set forth in a written software license agreement between you and FICO (or a FICO affiliate). Use of this documentation and the software described in it must conform strictly to the foregoing permitted uses, and no other use is permitted.

Contents

Index

Glossary