API Concepts

example.md

Users Collection Resource

Get some users

Example Request (collection resource)

GET https://example.com/users?offset=0&limit=10

Example Response

[{
  "href": "https://example.com/users?offset=0&limit=10",
  "offset": 0,
  "limit": 10,
  "items": [{
    "id": 45,
    "href": "https://example.com/users/45",
    "name": "Joe",
    "email": "[email protected]",
    "profile": {
      "href": "http://example.com/profiles/3567"
    },
    "images": {
      "href": "http://example.com/images?user.id=45&offset=0&limit=10"
    }
  }]
}]

Get some users and expand their profiles (collection resource with link expansion)

Example Request

GET https://example.com/users?offset=0&limit=10&expand=profile

Example Response

[{
  "href": "https://example.com/users?offset=0&limit=10",
  "offset": 0,
  "limit": 10,
  "items": [{
    "id": 45,
    "href": "https://example.com/users/45",
    "name": "Joe",
    "email": "[email protected]",
    "profile": {
      "id": 3567,
      "href": "http://example.com/profiles/3567",
      "language": "EN_US",
      "favorite_color": "red"
    },
    "images": {
      "href": "http://example.com/images?user.id=45&offset=0&limit=10"
    }
  }]
}]

Get some users whose favorite color is red (collection resource, searching a linked resource by attribute value)

Example Request

GET https://example.com/users?offset=0&limit10&profile.favorite_color=red

Example Response

[{
  "href": "https://example.com/users?offset=0&limit=10",
  "offset": 0,
  "limit": 10,
  "items": [{
    "id": 45,
    "href": "https://example.com/users/45",
    "name": "Joe",
    "email": "[email protected]",
    "profile": {
      "href": "http://example.com/profiles/3567"
    },
    "images": {
      "href": "http://example.com/images?user.id=45&offset=0&limit=10"
    }
  }]
}]

Get some users and expand their images (collection resource, link expansion with pagination information)

Example Request

GET https://example.com/users?offset=0&limit10&expand=images(offset:0,limit:10)

Example Response

[{
  "href": "https://example.com/users?offset=0&limit=10",
  "offset": 0,
  "limit": 10,
  "items": [{
    "id": 45,
    "href": "https://example.com/users/45",
    "name": "Joe",
    "email": "[email protected]",
    "profile": {
      "href": "http://example.com/profiles/3567"
    },
    "images": {
      "href": "http://example.com/images?user.id=45&offset=0&limit=10",
      "offset": 0,
      "limit": 10,
      "items": [{
        "id": 689,
        "href": "http://example.com/images/689",
        "hosted_url": "http://cdn.example.com/2346/122212.png",
        "image_height_px": 480,
        "image_width_px": 640
      }, {
        "id": 690,
        "href": "http://example.com/images/690",
        "hosted_url": "http://cdn.example.com/889/a345.png",
        "image_height_px": 640,
        "image_width_px": 480
      }]
    }
  }]
}]

open questions

1. Do you think that allowing a collection resource to be searched based on a property of a nested, linked resource is a bad idea? If a user has a profile and the profile has a favorite_color, do you think the way that I've allowed users to be searched by their profile's favorite color is sane?