API

The RESTful API can be found [not implemented].

Philosophy

The API is designed following these guidelines:

• The HTTP Status code reflects the result of the API call.

  • Some people think that HTTP status code should reflect the result of the pipe (the HTTP request itself), and that’s cool too. But that’s not what this project will use.

• API errors are returned with various 4xx HTTP status codes and have a JSON payload that attempts to follow RFC8707.

• PUT cannot create new resources.

• Using POST to create a resource will return the new resource.

• POST for verbs (none exist yet) will not return anything.

• PUT, PATCH, and DELETE will not return any data. It’s up to the end user to decide if they want compare old and new values. Typically this might look like:

  import requests
  old = requests.get("/metric/2")
  requests.patch("/metric/2" json={"units": "new_units"})
  new = requests.get("/metric/2")
  # Find the differences
  diff = {"old": {}, "new": {}}
  for item in old.keys():
      diff['old'][item] = old[item]
      diff['new'][item] = new[item]
  

• With a few exceptions, it’s up to the end user to determine which ID to act on. The API is not “smart” with regards to ID-like strings. For example, to delete the metric named foo.bar:

  import requests
  
  # You can't do this. Sorry!
  obj = requests.get("/metric/foo.bar")
  
  # instead you must do this (or similar):
  obj = request.get("/metric?name=foo.bar")['results'][0]
  rv = request.delete("/metric/{}".format(obj['metric_id']))
  assert rv.status_code == 204