API Entry Point

This document defines the API Entry Point (AEP) resource.

The AEP is the top level entry point for an OSDI API implementation. It provides links to other resource entry points, such as a collection of Petition resources in the system, documentation, and sometimes contains messages. By starting at the AEP and following successive links, a user should be able to reach all URLs available on the API.

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.

Back to top…

Fields

AEP Fields

A list of fields specific to the AEP resource.

Name Type Description
motd string The system “message of the day” – an informational message from the server.
max_pagesize integer The maximum number of records a server can return in a single query.
vendor_name string A string representing the vendor name
product_name string A string identifying the product name
osdi_version string A string identifying the OSDI Version
namespace string A string representing the prefix used for curies, identifiers, and other applicable places.

Back to top…

The links associated with this resource, available in the links section of the resource. Links that are part of the OSDI spec are typically prefixed with the osdi: namespace to aid in curie matching and readability.

Note: As with the entire OSDI specification, the specific links a compliant system supplies will vary between each system. In addition, systems may choose to embed a linked resource directly in the response in addition to linking to it in the links section, using the standard _embedded syntax described in the general overview documentation.

Note that on the AEP, links will often contain titles to inform new users about what each link leads to.

Name Type Description
self AEP* A self-referential link to the API Entry Point.
people People[]* A link to the collection of People resources in the system.
petitions Petitions[]* A link to the collection of Petition resources in the system.
events Events[]* A link to the collection of Event resources in the system.
forms Forms[]* A link to the collection of Form resources in the system.
fundraising_pages Fundraising Pages[]* A link to the collection of Fundraising Page resources in the system.
donations Donations[]* A link to the collection of Donation resources in the system.
tags Tags[]* A link to the collection of Tag resources in the system.
lists Lists[]* A link to the collection of list resources in the system.
queries Queries[]* A link to the collection of Query resources in the system.
questions Questions[]* A link to the collection of Question resources in the system.
metadata Metadata[]* A link to the Metadata endpoint in the system.
share_pages Share Pages[]* A link to the collection of Share Page resources in the system.
docs N/A A link to the human-readable documentation for the API system.
person_signup_helper Person Signup Helper* A link to the Person Signup Helper resource.

Back to top…

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 API Entry Point resource (GET)

Calling the AEP URL will return the API Entry Point resource with links to the rest of the API system.

Request

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

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

Response

200 OK

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

{
    "motd": "Welcome to the OSDI API Entry Point!",
    "vendor_name" : "Foobar Incorporated",
    "product_name" : "Curly Braces OSDI Server",
	"osdi_version" : "1.0",
    "max_pagesize": 25,
    "namespace": "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/",
            "title": "This API entry point"
        },
        "osdi:people": {
            "href": "https://osdi-sample-system.org/api/v1/people",
            "title": "The collection of people in the system"
        },
        "osdi:petitions": {
            "href": "https://osdi-sample-system.org/api/v1/petitions",
            "title": "The collection of petitions in the system"
        },
        "osdi:events": {
            "href": "https://osdi-sample-system.org/api/v1/events",
            "title": "The collection of events in the system"
        },
        "osdi:forms": {
            "href": "https://osdi-sample-system.org/api/v1/forms",
            "title": "The collection of forms in the system"
        },
        "osdi:fundraising_pages": {
            "href": "https://osdi-sample-system.org/api/v1/fundraising_pages",
            "title": "The collection of fundraising_pages in the system"
        },
        "osdi:donations": {
            "href": "https://osdi-sample-system.org/api/v1/donations",
            "title": "The collection of donations in the system"
        },
        "osdi:tags": {
            "href": "https://osdi-sample-system.org/api/v1/tags",
            "title": "The collection of tags in the system"
        },
        "osdi:lists": {
            "href": "https://osdi-sample-system.org/api/v1/lists",
            "title": "The collection of lists in the system"
        },
        "osdi:queries": {
            "href": "https://osdi-sample-system.org/api/v1/queries",
            "title": "The collection of queries in the system"
        },
        "osdi:questions": {
            "href": "https://osdi-sample-system.org/api/v1/questions",
            "title": "The collection of questions in the system"
        },
        "osdi:metadata": {
            "href": "https://osdi-sample-system.org/api/v1/metadata",
            "title": "The collection of metadata resources in the system"
        },	
        "osdi:share_pages": {
            "href": "https://osdi-sample-system.org/api/v1/share_pages",
            "title": "The collection of share pages in the system"
        },
        "docs": {
            "href": "https://osdi-sample-system.org/docs/v1/",
            "title": "Documentation",
            "name": "Docs",
            "index": "index"
        },
        "osdi:person_signup_helper": {
            "href": "https://osdi-sample-system.org/api/v1/people/person_signup",
            "title": "The person signup helper for the system"
        }
    }
}

Back to top…