API Design Notes

Profile Machine readable or not? If Machine readable, what format?

ALPS Document
JSON-LD Context
Web Page using XMDP Format

URL Design Doesn't Matter

Don't rely on URL to convey the application-level semantics of your API. Leave that to media type definitions and profiles.

###API Testing YouTypeIt GET Billboard

curl -v -X GET http://localhost:1337/api/ -H "Connection: close" -H "Cache-Control: no-cache"

POST New Message

curl -v -X POST -d '{"template":{"data":[{"name":"text","value":"testing"},{"name":"junk","value":""}]}}' http://localhost:1337/api/ -H "Content-Type: application/vnd.collection+json" -H "Connection: close" -H "Cache-Control: no-cache"

###Sample Collection+JSON Response Body

{
  "collection": {
    "version": "1.0",
    "links": [
      {
        "href": "http://localhost:1337/movie-alps.xml",
        "rel": "profile"
      }
    ],
    "href": "http://localhost:1337/api/",
    "items": [
      {
        "href": "http://localhost:1337/api/613856331910938",
        "data": [
          {
            "name": "description",
            "value": "An exclusive golf course has to deal with a brash new member and a destructive dancing gopher.",
            "prompt": "description of movie"
          },
          {
            "name": "datePublished",
            "value": "2013-03-28T21:51:08.406Z",
            "prompt": "date movie was published"
          },
          {
            "name": "name",
            "value": "Caddyshack",
            "prompt": "title of the movie"
          },
          {
            "name": "about",
            "value": "An exclusive golf course has to deal with a brash new member and a destructive dancing gopher.",
            "prompt": "short description of this item"
          },
          {
            "name": "genre",
            "value": "comedy",
            "prompt": "movie genre"
          },
          {
            "name": "version",
            "value": 1,
            "": "version of this release"
          },
          {
            "name": "timeRequired",
            "value": "PT180M",
            "prompt": "time required to view this movie also known as duration"
          },
          {
            "name": "contentRating",
            "value": 5,
            "prompt": "rating of the movie (1-5)"
          }
        ],
        "links": [
          {
            "name": "director",
            "rel": "director",
            "prompt": "the director of the movie",
            "href": "/contacts/abcdefghijk",
            "render": "link"
          }
        ]
      }
    ],
    "template": {
      "data": [
        {
          "name": "description",
          "value": "",
          "prompt": "description of movie"
        },
        {
          "name": "datePublished",
          "value": "",
          "prompt": "date movie was published"
        },
        {
          "name": "name",
          "value": "",
          "prompt": "title of the movie"
        },
        {
          "name": "about",
          "value": "",
          "prompt": "short description of this item"
        },
        {
          "name": "genre",
          "value": "",
          "prompt": "movie genre"
        },
        {
          "name": "version",
          "value": "",
          "prompt": "version of this release"
        },
        {
          "name": "timeRequired",
          "value": "",
          "prompt": "time required to view this movie also known as duration"
        },
        {
          "name": "contentRating",
          "value": "",
          "prompt": "rating of the movie (1-5)"
        }
      ]
    }
  }
}