Metadata

This page defines the Metadata Endpoint.

Metadata endpoint is a collection of resources that can be queried to gather information needed to work with OSDI resources. Metadata endpoint is generic endpoint to cover all other API resources that can provide information on main stream OSDI Endpoints like Events, Petitions, People etc. For instance, to record Canvass[] responses precisely, it is essential for the client to get the available options for canvass fields (ex: status codes or contact types). Collection of canvass fields supported by the system can be obtained by querying the resources available under the metadata endpoint.

Sections

Endpoints and URL structures

OSDI does not specify specific endpoints and link structures for compliant systems to use. Rather, because OSDI is a HAL+JSON API, endpoints and structures are defined in the links section of each returned resource, starting with the API Entry Point link.

HAL’s link structure lets an API consumer move through API levels, resources, and collections by parsing and following links. While most systems will not change the value of their links often and obey RESTful design principles, the value of each link when that resource is retrieved is the only canonical value, and it can change at any time.

The link relation label for Metadata endpoint is osdi:metadata and the link relation label for metadata resources will be under osdi:<metadata_url>, for instance osdi:canvass_response_codes has list of canvass status codes supported by the system.

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.

Scenario: Retrieving the collection of resources under metadata endpoint (GET)

Metadata endpoint is presented as collections of resources. For example, calling the metadata endpoint will return a collection of resources that the system supports.

Request

GET https://osdi-sample-system.org/api/v1/metadata

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

Response

200 OK

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

{
  "name": "OSDI Sample System",
  "_links": {
    "curies": [
      {
        "name": "osdi",
        "href": "https://osdi-sample-system.org/docs/v1/{rel}",
        "templated": true
      }
    ],
    "self": {
      "href": "https://osdi-sample-system.org/api/v1/metadata",
      "title": "OSDI Metadata"
    },
    "osdi:canvass_response_codes": {
      "href": "https://osdi-sample-system.org/api/v1/metadata/canvass_response_codes",
      "title": "The collection of canvass response codes in the system"
    },
    "osdi:canvass_contact_types": {
      "href": "https://osdi-sample-system.org/api/v1/metadata/canvass_contact_types",
      "title": "The collection of canvass contact types in the system"
    },
    "osdi:canvass_input_types": {
      "href": "https://osdi-sample-system.org/api/v1/metadata/canvass_input_types",
      "title": "The collection of canvass input types in the system"
    }
  }
}

Back to top…

Scenario: Retrieving the collection of canvass response codes (GET)

This resource is a collection of canvass response codes supported by the system.

Request

GET https://osdi-sample-system.org/api/v1/metadata/canvass_response_codes

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

Response

200 OK

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

{
    "origin_system": "OSDI Sample System",
    "name": "Available response codes",
    "description": "Available response codes",
    "identifiers": [
        "osdi_sample_system:response_codes"
    ],
    "_links": {
        "self": {
            "href": "https://osdi-sample-system.org/api/v1/metadata/canvass_response_codes"
        },
        "curies": [
            {
                "name": "osdi",
                "href": "http://osdi-sample-system.org/osdi#{rel}",
                "templated": true
            }
        ]
    },
    "response_codes": [
        {
            "response_code": "59",
            "name": "Bounced"
        },
        {
            "response_code": "18",
            "name": "Busy"
        },
        {
            "response_code": "17",
            "name": "Call Back"
        },
    ]
}

Back to top…

Scenario: Retrieving the collection of canvass contact types (GET)

This resource is a collection of canvass contact types supported by the system.

Request

GET https://osdi-sample-system.org/api/v1/metadata/canvass_contact_types

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

Response

200 OK

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

{
    "origin_system": "OSDI Sample System",
    "name": "Available contact types",
    "description": "Available contact types",
    "identifiers": [
        "osdi_sample_system:contact_types"
    ],
    "_links": {
        "self": {
            "href": "https://osdi-sample-system.org/api/v1/metadata/canvass_contact_types"
        },
        "curies": [
            {
                "name": "osdi",
                "href": "http://osdi-sample-system.org/osdi#{rel}",
                "templated": true
            }
        ]
    },
    "contact_types": [
        {
            "contact_type": "1",
            "name": "Phone"
        },
        {
            "contact_type": "2",
            "name": "Walk"
        },
    ]
}

Back to top…

Scenario: Retrieving available canvass response codes for contact types (GET)

This resource is a collection of canvass response codes available for given contact type.

Request

GET https://osdi-sample-system.org/api/v1/metadata/canvass_response_codes?contacttype=1

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

Response

200 OK

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

{
    "origin_system": "OSDI Sample System",
    "name": "Available response codes",
    "description": "Available contact types",
    "identifiers": [
        "osdi_sample_system:response_codes"
    ],
    "_links": {
        "self": {
            "href": "https://osdi-sample-system.org/api/v1/metadata/canvass_response_codes?contacttype=1"
        },
        "curies": [
            {
                "name": "osdi",
                "href": "http://osdi-sample-system.org/osdi#{rel}",
                "templated": true
            }
        ]
    },
    "response_codes": [
        {
            "response_code": "18",
            "name": "Busy"
        },
        {
            "response_code": "17",
            "name": "Call back"
        },
    ]
}

Back to top…

Scenario: Retrieving the collection of canvass input types (GET)

This resource is a collection of canvass input types supported by the system.

Request

GET https://osdi-sample-system.org/api/v1/metadata/canvass_input_types

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

Response

200 OK

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

{
    "origin_system": "OSDI Sample System",
    "name": "Available input types",
    "description": "Available input types",
    "identifiers": [
        "osdi_sample_system:input_types"
    ],
    "_links": {
        "self": {
            "href": "https://osdi-sample-system.org/api/v1/metadata/canvass_input_types"
        },
        "curies": [
            {
                "name": "osdi",
                "href": "http://osdi-sample-system.org/osdi#{rel}",
                "templated": true
            }
        ]
    },
    "input_types": [
        {
            "input_type": "11",
            "name": "API"
        },
        {
            "input_type": "4",
            "name": "Bulk"
        },
        {
            "input_type": "2",
            "name": "Manual"
        },
    ]
}

Back to top…