Status: Experimental

The content here is classified as Experimental. Experimental content is in development and not complete. It is published to invite feedback and enable implementation prototyping with a goal of eventual inclusion in the main specification. Implementers should recognize that this content may change

Errors

OSDI reports response codes and errors according to a standard schema. A combination of HTTP response codes and error objects is used to communicate the success or failure of a request.

Sections:

Background
- Atomic vs Non-Atomic Requests
- Response Codes for Atomic Requests
Error Fields
Related Objects
- Resource Status
- Error Description
Scenarios
- Atomic Request
- Non-Atomic Request

Back to top…

The link relation label for an Error resource is osdi:error for a single Error resource.

Background

Atomic vs Non-Atomic Requests

While most OSDI requests are atomic (i.e., the request either succeeds completely, possibly changing the state of the system, or fails completely, leaving system unchanged), it is possible to create non-atomic requests using helpers.

For example, the Person Signup Helper allows consumers to create a Person and a Tagging for the person in a single request. However, if the Person resource is valid but the Tagging is not, the Person may be created but the Tagging may not be created.

The osdi:error object for both types of requests is identical, except that atomic requests include only a single resource_status object, and non-atomic requests include multiple resource_status objects. For non-atomic requests, if some resource(s) were created or updated as part of the request, the server may add these resources to the response, alongside the osdi:error resource.

Back to top…

Response Codes for Atomic Requests

The following response codes correspond to success or failure of different kinds of atomic requests. Response codes may be provided in the body of the response using the response_code field, unless forbidden by the HTTP spec (e.g., if the response code is 204).

Type of request	Example	Description of result	Response Response Code	Response Body
Any	n/a	Unexpected server error	500	ErrorDescription indicating unexpected error; reference_code is recommended
Any	n/a	Request not supported	500	ErrorDescription indicating not-implemented
Any	n/a	API key not valid	401	n/a
Any	n/a	API key not allowed to execute this method	403	n/a
Read collection of resources	GET https://osdi-sample-system.org/api/v1/questions/	At least one resource found	200	Representation of list of resources found
Read collection of resources	GET https://osdi-sample-system.org/api/v1/questions/	No resources found	200	Either HAL empty collection document or empty JSON element {}
Read single resource or subresource of single resource	GET https://osdi-sample-system.org/api/v1/questions/d91b4b2e-ae0e-4cd3-9ed7-d0ec501b0baa	Resource found	200	Representation of resource found
Read single resource or subresource of single resource	GET https://osdi-sample-system.org/api/v1/questions/d91b4b2e-ae0e-4cd3-9ed7-d0ec501b0baa	Resource not found	404	n/a
Create single resource	POST https://osdi-sample-system.org/api/v1/questions/	Resource in request is not valid	400	ErrorDescription[]
Create single resource	POST https://osdi-sample-system.org/api/v1/questions/	Resource in request is valid and was created	201	Representation of created resource
Update single resource	PUT https://osdi-sample-system.org/api/v1/questions/d91b4b2e-ae0e-4cd3-9ed7-d0ec501b0baa	Resource in request is not valid	400	ErrorDescription[]
Update single resource	PUT https://osdi-sample-system.org/api/v1/questions/d91b4b2e-ae0e-4cd3-9ed7-d0ec501b0baa	Resource in request is valid and was updated	200	Representation of updated resource
Delete single resource	DELETE https://osdi-sample-system.org/api/v1/questions/d91b4b2e-ae0e-4cd3-9ed7-d0ec501b0baa	Resource not found	404	ErrorDescription[]
Delete single resource	DELETE https://osdi-sample-system.org/api/v1/questions/d91b4b2e-ae0e-4cd3-9ed7-d0ec501b0baa	Resource found and deleted	204	n/a

Back to top…

Error Fields

A list of fields specific to the Error resource.

Name	Type	Description
request_type	enum	One of “atomic”, “non-atomic”
response_code	int	An indication of the success or failure of the request as a whole. Atomic requests should provide the appropriate value from the Response Codes for Atomic Requests table. Non-atomic requests should provide a value of 400.
resource_status	ResourceStatus[]	An indication of the success or failure of each individual request.

Back to top…

Resource Status

Name	Type	Description
resource	string	The name of the OSDI resource involved in the request; for example “osdi:person”.
response_code	int	The success or failure of the request for the resource, as indicated in the Response Codes for Atomic Requests table.
error_descriptions	ErrorDescription[]	A description of the error(s) which caused the request for the resource to fail.

Back to top…

Error Description

Name	Type	Description
error_code	string	A machine-readable reason for the error: for example, `START_DATE_AFTER_END_DATE`
description	string	A human-readable reason for the error: for example, “The start date occurs after the end date.”
properties	string[]	An array of strings referencing the property or properties in the resource which cause the error; for example, `['start_date', 'end_date']`.
hint	string	An indication of how to resolve this error. For example, if the property is an email address which is deemed invalid according to a regular expression, the regular expression can be provided here; e.g. `.+@.+(\..+)+`
reference_code	string	A string which refers to an internal error report which may be used to diagnose the problem; for example, “Logger-2015-03-10-cecc4e52-b350-4dac-87fc-39fc819f8c48”

Back to top…

Scenarios

The scenarios below show some common Create, Read, Update, Delete (CRUD) operations that can be performed on this resource, as well as any resource-specific behaviors worth highlighting. The following examples are for informational purposes. The authoritative resource definitions are above in the Fields tables and should be followed in the event of a conflict with the examples.

Atomic Request

The consumer sends a request, which is expected to succeed or fail atomically.

This request fails for two reasons. First, the implementing system does not allow multiple-choice responses for questions of type “Paragraph”. Second, because the implementing system uses a regular expression for validating the name property of question responses, but one of the question responses does not match that regular expression. Both errors are reported.

Request

POST https://osdi-sample-system.org/api/v1/questions/

Header:
OSDI-API-Token:[your api key here]

{
    "identifiers": [
        "foreign_system:1"
    ],
    "name": "Issues question",
    "title": "Which questions do you care about?",
    "description": "<p>Which issues do you care about? Select all that apply.</p>",
    "summary": "Issues the person cares about",
    "question_type": "Paragraph",
    "responses": [
      {
        "key": "hc",
        "name": "healthcare",
        "title": "Health care"
      },
      {
        "key": "env",
        "name": "environment",
        "title": "Environment"
      },
      {
        "key": "ec & jobs",
        "name": "economy",
        "title": "Economy and jobs"
      }
    ]
}

Response

400 Bad Request

Content-Type: application/hal+json
Cache-Control: max-age=0, private, must-revalidate

{
  "osdi:error": {
    "request_type": "atomic",
    "response_code": 400,
    "resource_status": [
       {
        "resource": "osdi:question",
        "response_code": 400,
        "error_descriptions": [
          {
            "error_code": "PARAGRAPH_CANNOT_HAVE_RESPONSES",
            "description": "A question of type 'Paragraph' may not have responses.",
            "properties": [ 'question_type', 'responses' ]
          },
          {
            "error_code": "RESPONSE_NAME_INVALID",
            "description": "The response name 'ec & jobs' is invalid.",
            "properties": [ 'responses[2].name' ],
            "hint": "^[A-Za-z0-9_]+$"
          }
        ]
       }
    ]
  }
}

Back to top…

Non-Atomic Request

In this scenario, a consumer attempts to use the Person Signup Helper to create a Person, add a Tagging to that person, and add the person to the List. The Person object is valid, but the Tagging is invalid because the Tags in question do not exist. Moreover the implementing system does not support the osdi:item resource, and therefore adding the person to the list fails, as well. The Person is created but is not Tagged or added to a List. The success of the Person creation, failure of the Tagging creation, and failure to add to a List are all reported.

Because the request as a whole is invalid, an Error with response code 400 is returned.

The server has also provided detail about the created Person via an osdi:person response.

Request

POST https://osdi-sample-system.org/api/v1/people/person_signup_helper/

Header:
OSDI-API-Token:[your api key here]

{
    "person": {
        "identifiers": [
            "foreign_system:1"
        ],
        "family_name": "Edwin",
        "given_name": "Labadie",
        "additional_name": "Marques",
        "origin_system": "OpenSupporter",
        "email_addresses": [
            {
                "address":"test-3@example.com",
                "primary": true,
                "address_type": "Personal"
            }
        ],
        "postal_addresses": [
            {
                "primary": true,
                "address_lines": [
                    "935 Ed Lock"
                ],
                "locality": "New Dudley",
                "region": "MN",
                "postal_code": "17678",
                "country": "US",
                "address_type": "Home",
                "status": "Verified"
            }
        ],
        "phone_numbers": [
            {
                "primary": true,
                "number": 19876543210,
                "number_type": "Mobile",
                "sms_capable": true
            }
        ],
        "gender": "Male"
    },
    "add_tags": [
        "volunteer"
    ],
    "add_lists": [
        "supporters"
    ]
}

Response

400 Bad Request

Content-Type: application/hal+json
Cache-Control: max-age=0, private, must-revalidate

{
    "osdi:error": {
      "request_type": "non-atomic",
      "response_code": 400,
      "resource_status": [
        {
          "resource": "osdi:person",
          "response_code": 201
        },
        {
          "resource": "osdi:tagging",
          "response_code": 400,
          "errors": [
            {
              "code": "TAG_NAME_DOES_NOT_EXIST",
              "description": "The tag name 'volunteer' does not exist.",
              "properties": [ 'add_tags' ]
            },
          ]
        },
        {
          "resource": "osdi:item",
          "response_code": 500,
          "errors": [
            {
              "code": "NOT_SUPPORTED",
              "description": "The system does not support resources of this type."
            }
          ]
        }
      ]
   }
   "osdi:person": {
      "identifiers": [
          "osdi_sample_system:d91b4b2e-ae0e-4cd3-9ed7-d0ec501b0bc3",
          "foreign_system:1"
      ],
      "origin_system": "OSDI Sample System",
      "created_date": "2014-03-20T21:04:31Z",
      "modified_date": "2014-03-20T21:04:31Z",
      "given_name": "Labadie",
      "additional_name": "Marques",
      "family_name": "Edwin",
      "gender": "Male",
      "postal_addresses": [
          {
              "primary": true,
              "address_type": "Home",
              "address_lines": [
                  "935 Ed Lock"
              ],
              "locality": "New Dudley",
              "region": "MN",
              "postal_code": "17678",
              "country": "US",
              "language": "en",
              "location": {
                  "latitude": 38.919,
                  "longitude": -77.0379,
                  "accuracy": "Rooftop"
              }
              "status": "Verified"
          }
      ],
      "email_addresses": [
          {
              "primary": true,
              "address": "test-3@example.com",
              "address_type": "Personal"
          }
      ],
      "phone_numbers": [
          {
              "primary": true,
              "number": "19876543210",
              "number_type": "Mobile",
              "sms_capable": true,
          }
      ],
      "_links": {
          "self": {
              "href": "https://osdi-sample-system.org/api/v1/people/d91b4b2e-ae0e-4cd3-9ed7-d0ec501b0bc3"
          },
          "osdi:answers": {
              "href": "https://osdi-sample-system.org/api/v1/people/d91b4b2e-ae0e-4cd3-9ed7-d0ec501b0bc3/answers"
          },
          "osdi:attendance": {
              "href": "https://osdi-sample-system.org/api/v1/people/d91b4b2e-ae0e-4cd3-9ed7-d0ec501b0bc3/attendance"
          },
          "osdi:signatures": {
              "href": "https://osdi-sample-system.org/api/v1/people/d91b4b2e-ae0e-4cd3-9ed7-d0ec501b0bc3/signatures"
          },
          "osdi:submissions": {
              "href": "https://osdi-sample-system.org/api/v1/people/d91b4b2e-ae0e-4cd3-9ed7-d0ec501b0bc3/submissions"
          },
          "osdi:donations": {
              "href": "https://osdi-sample-system.org/api/v1/people/d91b4b2e-ae0e-4cd3-9ed7-d0ec501b0bc3/donations"
          },
          "osdi:taggings": {
              "href": "https://osdi-sample-system.org/api/v1/people/d91b4b2e-ae0e-4cd3-9ed7-d0ec501b0bc3/taggings"
          },
          "osdi:items": {
              "href": "https://osdi-sample-system.org/api/v1/people/d91b4b2e-ae0e-4cd3-9ed7-d0ec501b0bc3/items"
          }
      }
   }
}

Back to top…

Open Supporter Data Interface Documentation

Errors

Sections:

Background

Atomic vs Non-Atomic Requests

Response Codes for Atomic Requests

Error Fields

Related Objects

Resource Status

Error Description

Scenarios

Atomic Request

Request

Response

Non-Atomic Request

Request

Response