Skip to content

Latest commit

 

History

History
206 lines (182 loc) · 6.13 KB

lists.md

File metadata and controls

206 lines (182 loc) · 6.13 KB
Raw
layout title
default
Lists

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

Items

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"

Scenarios

Get the list of lists

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 a list

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",
            }
        }
}

Create a new list

POST /api/v1/lists

{
    "name": "Ref74 Volunteers",
    "description": "A list containing all of our volunteers"
}

Retrieve the items in a list

URL

GET api/v1/lists/{id}/items

Response

{
  "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
    ]
  }
}