layout | title |
---|---|
default |
Lists |
Lists are arbitrary collections of items. Items can be added or deleted with the API.
A list is a resource type that contains list metadata as well as a link to the items collection. The items collection is the actual list resources.
Lists can represent either arbitrary lists generated by users, or the result of server processes such as query snapshots. Some servers may allow lists to be modified via the API; some may not.
Name | Type | Description |
---|---|---|
identifiers | Identifier[] | An array of identifiers |
origin_system | string | Human readable identifier of the system where this list was created |
name | string | Name of list |
description | string | A description of a list, eg "2012 donors" |
items | Type[]* | A collection of items in the list |
An item is an individual member of a list, linked to a resource type such as a person. An item can be of any resource type.
name | type | description |
---|---|---|
identifiers | Identifier[] | An array of identifiers |
created_date | timestamp | time the item was created |
origin_system | string | Human readable identifier of the system where this item was created |
item_type | string | the type of item, eg "osdi:person" |
GET /api/v1/lists
200 OK
Content-Type: application/json
{
"total_pages": 1,
"page": 1,
"total_records": 1,
"_embedded": {
"lists": [
{
"identifiers": [
"open_supporter:1"
],
"name" : "Ref74 Supporters",
"origin_system": "OpenSupporter",
"description" : "The set of all supporters for Ref74",
"total_members" 3043, # computed field
"_links" : {
"self" : {
"href" : "api/v1/list/1"
},
"osdi:items" : {
"href" : "api/v1/list/1/items",
}
}
},
{
"identifiers": [
"open_supporter:2"
],
"name" : "Ref74 Donors",
"origin_system": "OpenSupporter",
"description" : "The set of all 2012 donors for Ref74",
"total_members" 3043, # computed field
"_links" : {
"self" : {
"href" : "api/v1/list/2"
},
"osdi:items" : {
"href" : "api/v1/list/2/items",
}
}
}
"_links": {
"self": {
"href": "http://osdi-prototype.herokuapp.com/api/v1/lists"
}
}
}
GET /api/v1/list/1
200 OK
Content-Type: application/json
{
"identifiers": [
"open_supporter:1"
],
"origin_system": "OpenSupporter",
"name" : "Ref74 Supporters",
"description" : "The set of all supporters for Ref74",
"total_members" 3043, # computed field
"created": datetime,
"updated": datetime,
"_links" : {
"self" : {
"href" : "api/v1/list/1"
},
"osdi:items" : {
"href" : "api/v1/list/1/items",
}
}
}
POST /api/v1/lists
{
"name": "Ref74 Volunteers",
"description": "A list containing all of our volunteers"
}
GET api/v1/lists/{id}/items
{
"total_pages": 5,
"per_page": 25,
"page": 1,
"total_records": 123,
"_links": {
"next": {
"href": "https://opensupporter.org/api/v1/lists/71f8feef-61c8-4e6b-9745-ec1d7752f298/items?page=2"
},
"self": {
"href": "https://opensupporter.org/api/v1/lists/71f8feef-61c8-4e6b-9745-ec1d7752f298/items"
},
"osdi:items": [
{
"href": "https://opensupporter.org/api/v1/lists/71f8feef-61c8-4e6b-9745-ec1d7752f298/items/82e909f9-1ac7-4952-bbd4-b4690a14bec2"
},
{
"href": "https://opensupporter.org/api/v1/lists/71f8feef-61c8-4e6b-9745-ec1d7752f298/items/a9ccd87c-97f4-48db-9e6b-507509091839"
},
//truncated for brevity
],
"curies": [
{
"name": "osdi",
"href": "https://opensupporter.org/docs/v1/{rel}",
"templated": true
}
]
},
"_embedded": {
"osdi:items": [
{
"_links": {
"self": {
"href": "https://opensupporter.org/api/v1/lists/71f8feef-61c8-4e6b-9745-ec1d7752f298/items/82e909f9-1ac7-4952-bbd4-b4690a14bec2"
},
"osdi:query": {
"href": "https://opensupporter.org/api/v1/lists/71f8feef-61c8-4e6b-9745-ec1d7752f298"
},
"osdi:person": {
"href": "https://opensupporter.org/api/v1/people/82e909f9-1ac7-4952-bbd4-b4690a14bec2"
}
},
"identifiers": [
"open_supporter:82e909f9-1ac7-4952-bbd4-b4690a14bec2"
],
"origin_system": "Open Supporter",
"created_at": "2014-03-18T22:25:31Z",
"modified_at": "2014-03-18T22:25:38Z",
"item_type": "osdi:person"
},
{
"_links": {
"self": {
"href": "https://opensupporter.org/api/v1/lists/71f8feef-61c8-4e6b-9745-ec1d7752f298/items/a9ccd87c-97f4-48db-9e6b-507509091839"
},
"osdi:query": {
"href": "https://opensupporter.org/api/v1/lists/71f8feef-61c8-4e6b-9745-ec1d7752f298"
},
"osdi:person": {
"href": "https://opensupporter.org/api/v1/lists/a9ccd87c-97f4-48db-9e6b-507509091839"
}
},
"identifiers": [
"open_supporter:a9ccd87c-97f4-48db-9e6b-507509091839"
],
"origin_system": "Open Supporter",
"created_at": "2014-03-18T22:24:24Z",
"modified_at": "2014-03-18T22:24:24Z",
"item_type": "osdi:person"
},
//truncated for brevity
]
}
}