Skip to content

Latest commit

 

History

History
228 lines (217 loc) · 5.09 KB

API_SPEC.md

File metadata and controls

228 lines (217 loc) · 5.09 KB
Raw

HostDB API Specification

Assume a sample host config like this:

---
Network:
  CNAME: somename.yourdomain.com
  IP: 1.2.3.4
HTTP Method End point Meaning Example
GET /v1 Get a list(newline separated) of all namespaces
PUT/POST/DELETE /v1 Not Supported
GET /v1/namespace Get a list(newline separated) of all keys in the namespace /v1/hosts
PUT/POST/DELETE /v1/namespace Not Supported
GET /v1/namespace/key Get config for a particular key /v1/tags/web_servers
PUT /v1/namespace/key Create a new key. Overwrite existing. /v1/tags/DB_servers PUTDATA: value=uri_escaped_yaml_data
POST /v1/namespace/key Rename a key /v1/hosts/server1.yourdomain.com POSTDATA: newname=server2.yourdomain.com.com
DELETE /v1/namespace/key Delete a key and all its meta information. /v1/tags/testtag
GET /v1/namespace/key/members Get members of a key as a list expanding all inherited members. /v1/tags/web_servers/members
GET /v1/namespace/key/members?raw=true Get members in raw format. Does not expand inherited members. /v1/tags/web_servers/members?raw=true
PUT /v1/namespace/key/members Set members of a key (raw format) /v1/tags/web_servers/members PUTDATA: value=uri_escaped_list
POST /v1/namespace/key/members Not Supported
DELETE /v1/namespace/key/members Delete all members /v1/tags/web_servers/members
GET /v1/namespace/key/members/hostname Just returns hostname if it exists in members /v1/tags/VM/testVM1
PUT /v1/namespace/key/members/hostname Add a member /v1/tags/VM/testVM1
POST /v1/namespace/key/members/hostname Rename a member /v1/tags/VM/testVM1 POSTDATA: newname=testVM2
DELETE /v1/namespace/key/members/hostname Delete a member /v1/tags/VM/testVM2
GET /v1/namespace/key/config[/config/…] Get a specific item inside key’s config /v1/hosts/server1.yourdomain.com/Network
PUT /v1/namespace/key/config[/config/…] Set a specific item inside key’s config /v1/hosts/server1.yourdomain.com/Network PUTDATA: value=uri_escaped_yaml_data
POST /v1/namespace/key/config[/config/…] Rename a specific item inside key’s config /v1/hosts/server1.yourdomain.com/Network/CNAME POSTDATA: newname=cname
DELETE /v1/namespace/key/config[/config/…] Delete a specific item inside key’s config /v1/hosts/server1.yourdomain.com/Network/IP

Extra functions:

HTTP Method End Point Meaning Example
GET any_uri?search=regex output only lines matching the regex /v1/hosts?search=stage
GET /v1/hosts/key?meta=parents&from=namespace Parents of a host in a namespace. Like ‘tagofhost’. /v1/hosts/server1.yourdomain.com?meta=parents&from=tags
GET /v1/hosts/key?meta=derived&from=namespace Derived Config of a host in a namespace. (Combined config of all parents) /v1/hosts/server1.yourdomain.com?meta=derived&from=tags
GET any_uri?meta=revisions[&limit=n] Last n revision ids of an object. Default n=50. /v1/hosts/server1.yourdomain.com?meta=revisions&limit=10
GET any_uri?revision= Gives the contents of the object for the specified revision /v1/hosts/server1.yourdomain.com?revision=u2eoajwoiqjdoqw
GET any_url?foreach= Iterates over all keys generated from resource id get IPs of all web servers: v1/hosts/*/Network/IP?foreach=tags/web_servers/members

Auth functions:

HTTP Method End Point Meaning Example
POST /v1/auth/session create a new session token /v1/auth/session POSTDATA: username=user&password=secret
GET /v1/auth/session/ Validate a session token /v1/auth/session/aldha3i4rf738w7o5y5sey85iu
GET /v1/auth/can_modify?user=&id= check if user has permission to modify resource