pyfarm.master.api.tags module¶
Tag¶
Contained within this module are an API handling functions which can manage or query tags using JSON.
Bases:
flask.views.MethodView
A
GET
to this endpoint will list all agents associated with this tag.Request
GET /api/v1/tags/interesting/agents/ HTTP/1.1 Accept: application/json
Response
HTTP/1.1 201 CREATED Content-Type: application/json [ { "hostname": "agent3", "id": 1, "href": "/api/v1/agents/1 } ]
Statuscode 200: the list of agents associated with this tag is returned Statuscode 404: the tag specified does not exist
A
POST
will add an agent to the list of agents tagged with this tag The tag can be given as a string or as an integer (its id).Request
POST /api/v1/tags/interesting/agents/ HTTP/1.1 Accept: application/json { "agent_id": "dd0c6da2-0c91-42cf-a82f-6d503aae43d3" }
Response (agent newly tagged)
HTTP/1.1 201 CREATED Content-Type: application/json { "href": "/api/v1/agents/1", "id": 1 }
Request
POST /api/v1/tags/interesting/agents/ HTTP/1.1 Accept: application/json { "agent_id": "dd0c6da2-0c91-42cf-a82f-6d503aae43d3" }
Response (agent already had that tag)
HTTP/1.1 200 OK Content-Type: application/json { "href": "/api/v1/agents/1", "id": 1 }
Statuscode 200: an existing tag was found and returned Statuscode 201: a new tag was created Statuscode 400: there was something wrong with the request (such as invalid columns being included) Statuscode 404: either the tag or the referenced agent does not exist
Bases:
flask.views.MethodView
A
DELETE
to this endpoint will delete the tag under this URI, including all relations to tags or jobs.Request
DELETE /api/v1/tags/interesting HTTP/1.1 Accept: application/json
Response
HTTP/1.1 201 CREATED Content-Type: application/json { "id": 1, "tag": "interesting" }
Statuscode 204: the tag was deleted or did not exist in the first place
A
GET
to this endpoint will return the referenced tag, either by name or id, including a list of agents and jobs associated with it.Request
GET /api/v1/tags/interesting HTTP/1.1 Accept: application/json
Response
HTTP/1.1 200 OK Content-Type: application/json { "agents": [{ "hostname": "agent3", "href": "/api/v1/agents/94522b7e-817b-4358-95da-670b31aad624", "id": 1 }], "id": 1, "jobs": [], "tag": "interesting" }
Statuscode 200: no error Statuscode 404: tag not found
A
PUT
to this endpoint will create a new tag under the given URI. If a tag already exists under that URI, it will be deleted, then recreated. Note that when overwriting a tag like that, all relations that are not explicitly specified here will be deleted You can optionally specify a list of agents or jobs relations as integers in the request data.You should only call this by id for overwriting an existing tag or if you have a reserved tag id. There is currently no way to reserve a tag id.
Request
PUT /api/v1/tags/interesting HTTP/1.1 Accept: application/json { "tag": "interesting" }
Response
HTTP/1.1 201 CREATED Content-Type: application/json { "id": 1, "tag": "interesting" }
Request
PUT /api/v1/tags/interesting HTTP/1.1 Accept: application/json { "tag": "interesting", "agents": [1] "jobs": [] }
Response
HTTP/1.1 201 CREATED Content-Type: application/json { "id": 1, "tag": "interesting" }
Statuscode 201: a new tag was created Statuscode 400: there was something wrong with the request (such as invalid columns being included) Statuscode 404: a referenced agent or job does not exist
Bases:
flask.views.MethodView
A
GET
to this endpoint will return a list of known tags, with id. Associated agents and jobs are included for every tag:rtype : object .. http:get:: /api/v1/tags/ HTTP/1.1
Request
GET /api/v1/tags/ HTTP/1.1 Accept: application/json
Response
HTTP/1.1 200 OK Content-Type: application/json [ { "agents": [ 1 ], "jobs": [], "id": 1, "tag": "interesting" }, { "agents": [], "jobs": [], "id": 2, "tag": "boring" } ]
Statuscode 200: no error
A
POST
to this endpoint will do one of two things:- create a new tag and return the row
- return the row for an existing tag
Tags only have one column, the tag name. Two tags are automatically considered equal if the tag names are equal.
Request
POST /api/v1/tags/ HTTP/1.1 Accept: application/json { "tag": "interesting" }
Response (new tag create)
HTTP/1.1 201 CREATED Content-Type: application/json { "id": 1, "tag": "interesting" }
Request
POST /api/v1/tags/ HTTP/1.1 Accept: application/json { "tag": "interesting" }
Response (existing tag returned)
HTTP/1.1 200 OK Content-Type: application/json { "id": 1, "tag": "interesting" }
Statuscode 200: an existing tag was found and returned Statuscode 201: a new tag was created Statuscode 400: there was something wrong with the request (such as invalid columns being included)
Returns the basic schema of
Tag
Request
GET /api/v1/tags/schema/ HTTP/1.1 Accept: application/json
Response
HTTP/1.1 200 OK Content-Type: application/json { "id": "INTEGER", "tag": "VARCHAR(64)" }
Statuscode 200: no error