| layout | title |
|---|---|
default |
Example Resource |
Introductory paragraphs describing the resource.
{% include endpoints_and_url_structures.md %}
The link relation label for a Example Resource resource is osdi:example_resource for a single Example Resource resource or osdi:example_resources for a collection of Example Resource resources.
{% include fields_intro.md %}
{% include global_fields.md %}
A list of fields specific to the Example Resource.
| Name | Type | Description |
|---|---|---|
| field1 | string | field1 description |
| field2 | ExampleObject | An instance of an Example Object |
| field3 | ExampleObject[] | An array of Example Objects |
These objects included in the table above are broken out into their own tables for readability, rather than independent resources with their own endpoints.
| Name | Type | Description |
|---|---|---|
| field1 | string | Description of field1 |
| field2 | string | Description of field2 |
{% include links_intro.md %}
| Name | Type | Description |
|---|---|---|
| self | Example Resource* | A self-referential link to the resource. |
| linked_resource1 | LinkedResourceType1* | A link to the instance of LinkedResourceType1 |
| linked_resource2 | LinkedResourceType2[]* | A link to the collection of resources |
{% include helpers_intro.md %}
| Name | Description |
|---|---|
| example_helper1 | Description of helper's purpose. |
| example_helper2 | Description of helper's purpose. |
{% include scenarios_intro.md %}
Resource Example resources are sometimes presented as collections of resource example. For example, calling the resource example endpoint will return a collection of all the resource example stored in the system's database associated with your api key.
GET https://osdi-sample-system.org/api/v1/resource
Header:
OSDI-API-Token:[your api key here]200 OK
Content-Type: application/hal+json
Cache-Control: max-age=0, private, must-revalidate
{
"total_pages": 88,
"per_page": 25,
"page": 1,
"total_records": 2188,
"_links": {
"next": {
"href": "https://osdi-sample-system.org/api/v1/resource?page=2"
},
"curies": [
{
"name": "osdi",
"href": "https://osdi-sample-system.org/docs/v1/{rel}",
"templated": true
}
],
"self": {
"href": "https://osdi-sample-system.org/api/v1/resource"
},
//other links here
},
"_embedded": {
"osdi:resource": [
//fields go here
]
}
}Calling an individual Resource Example resource will return the resource directly, along with all associated fields and appropriate links to additional information about the resource.
GET https://osdi-sample-system.org/api/v1/resource/d32fcdd6-7366-466d-a3b8-7e0d87c3cd8b
Header:
OSDI-API-Token:[your api key here]200 OK
Content-Type: application/hal+json
Cache-Control: max-age=0, private, must-revalidate
{
"identifiers": [
"osdi_sample_system:d91b4b2e-ae0e-4cd3-9ed7-d0ec501b0bc3",
"foreign_system:1"
],
"created_date": "2014-03-20T21:04:31Z",
"modified_date": "2014-03-20T21:04:31Z",
//more fields here
"_links": {
"self": {
"href": "https://osdi-sample-system.org/api/v1/resource/d91b4b2e-ae0e-4cd3-9ed7-d0ec501b0bc3"
},
//more links here
}
}Posting to the resource collection endpoint will allow you to create a new resource. The response is the new resource that was created. While each implementing system will require different fields, any optional fields not included in a post operation should not be set at all by the receiving system, or should be set to default values.
POST https://osdi-sample-system.org/api/v1/resource/
Header:
OSDI-API-Token:[your api key here]
{
//fields here
}200 OK
Content-Type: application/hal+json
Cache-Control: max-age=0, private, must-revalidate
{
"identifiers": [
"osdi_sample_system:d91b4b2e-ae0e-4cd3-9ed7-de9uemdse",
"foreign_system:1"
],
"created_date": "2014-03-20T21:04:31Z",
"modified_date": "2014-03-20T21:04:31Z",
// more fields/links here
}You can updating a resource by calling a PUT operation on that resource's endpoint. Your PUT should contain fields that you want to update. Missing fields will be ignored by the receiving system. Systems may also ignore PUT values, depending on whether fields you are trying to modify are read-only or not. You may set an attribute to nil by including the attribute using nil for value.
{% include array_warning.md %}
PUT https://osdi-sample-system.org/api/v1/resource/d91b4b2e-ae0e-4cd3-9ed7-de9uemdse
Header:
OSDI-API-Token:[your api key here]
{
// fields here
}200 OK
Content-Type: application/hal+json
Cache-Control: max-age=0, private, must-revalidate
{
"identifiers": [
"osdi_sample_system:d91b4b2e-ae0e-4cd3-9ed7-de9uemdse",
],
// more fields/links here
}You may delete a resource by calling the DELETE command on the resource's endpoint.
DELETE https://osdi-sample-system.org/api/v1/resource/d32fcdd6-7366-466d-a3b8-7e0d87c3cd8b
Header:
OSDI-API-Token:[your api key here]200 OK
Content-Type: application/hal+json
Cache-Control: max-age=0, private, must-revalidate
{
"notice": "This resource was successfully deleted."
}