REST Concepts

VOCUS APIs are designed to behave in a uniform fashion and to exchange JSON with any modern HTTP client.

Libraries Used in Examples

Examples are shown using JavaScript and c#, with the output format assumed to be JSON.

JavaScript: jQuery
c#: RestSharp

HTTP Response Codes

HTTP Status Code	Description
200 OK	The operation completed successfully. Check response body for return value(s).
201 Created	The operation completed successfully and a resource was created. Check response body for return value(s). The `Location` header may also contain a URL to the resource, though this URL may or may not be of immediate use to the caller.
400 Bad Request	The request was malformed in some way, e.g. missing or invalid values. This error can pertain to content or headers.
401 Unauthorized	Authentication was required, but authentication information is missing or invalid.
403 Forbidden	The caller was authenticated and identified, but not authorized to make the call. This status can also be returned due to a violation of OWASP security rules implemented by the Microsoft Application Gateway through which API traffic passes. If this is the case, the `Server` header in the response will contain a value similar to "Microsoft-Azure-Application-Gateway". Check for a malformed request or invalid headers. Polaris maintains detailed logs and can assist in troubleshooting.
415 Unsupported Media Type	Indicates a problem with the request payload. This error will usually be encountered and resolved during development, e.g. forgetting to add a request body or setting an unsupported `Content-Type` header.
500 Internal Server Error	An unexpected error caused by a bug or internal problem such as loss of connectivity to a database. The operation may be retried, but should be abandoned if it fails repeatedly.

Validation Errors

Details about the problem are returned as a JSON object, following the guidance of RFC 7808.

Field	Type	Description
type	string	A URI to a human readable summary of the type of problem that occurred. This is the primary identifier of the problem type.
instance	string	A correlation ID which can be provided to Polaris Aero for further research.
title	string	A short title for the error type.
detail	string	A human-readable explanation of the problem and guidance on how to solve it.
fieldErrors	array	Specific fields (if any) which caused the operation to fail. If a field name is present, there will always be at least one item in the corresponding array.
generalErrors	array	Other problems (if any) which caused the operation to fail.

Strings in the response JSON may contain user generated content. These should be HTML encoded before display in a web browser.

Sample Response

    var response = {
        title: "Error Validating Input Data",
        instance: "2oEUJCQtiST",
        type: "https://api.polarisaero.com/Help/Home/RestConcepts#validation-errors",
        detail: "First name can't be blank.",
        fieldErrors: {
            firstName: ["First name can't be blank."]
        },
        generalErrors: [],
    };

Server Errors

Server errors are always indicated with HTTP status code 500. If a user is waiting on the operation, a general, user-friendly message should be displayed to them, not the details of this error.

Server errors usually must be resolved by Polaris Aero. A handled server error will be logged with a correlation ID that is given to the caller. Include the correlation ID and the specific inputs used when reporting a server error.

Details about the problem are returned as a JSON object, following the guidance of RFC 7808.

Field	Type	Description
type	string	A URI to a human readable summary of the type of problem that occurred. This is the primary identifier of the problem type.
instance	string	A correlation ID which can be provided to Polaris Aero for further research.
title	string	A short title for the error type.
generalErrors	array	These error(s) may prove useful to a developer, but they should not be shown to an end user to avoid confusion.

Sample Response

    var response = {
        type: "https://api.polarisaero.com/Help/Home/RestConcepts#server-errors",
        instance: "2oEUJCQtiST",
        title: "Internal Server Error",
        // Likely a bug in API code; perhaps a missing check or logic error
        generalErrors: ["Null reference exception"]
    };

API Version 14.1.9203.25249