pyfarm.master.api.tags module¶

Tag¶

Contained within this module are an API handling functions which can manage or query tags using JSON.

class pyfarm.master.api.tags.AgentsInTagIndexAPI[source]¶

Bases: flask.views.MethodView

get(tagname=None)[source]¶

A GET to this endpoint will list all agents associated with this tag.

GET /api/v1/tags/<str:tagname>/agents/ HTTP/1.1¶

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

methods = ['GET', 'POST']¶

post(tagname=None)[source]¶

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).

POST /api/v1/tags/<str:tagname>/agents/ HTTP/1.1¶

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

class pyfarm.master.api.tags.SingleTagAPI[source]¶

Bases: flask.views.MethodView

delete(tagname=None)[source]¶

A DELETE to this endpoint will delete the tag under this URI, including all relations to tags or jobs.

DELETE /api/v1/tags/<str:tagname> HTTP/1.1¶

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

get(tagname=None)[source]¶

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.

GET /api/v1/tags/<str:tagname> HTTP/1.1¶

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

methods = ['DELETE', 'GET', 'PUT']¶

put(tagname=None)[source]¶

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.

PUT /api/v1/tags/<str:tagname> HTTP/1.1¶

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

class pyfarm.master.api.tags.TagIndexAPI[source]¶

Bases: flask.views.MethodView

get()[source]¶

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

methods = ['GET', 'POST']¶

post()[source]¶

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.

POST /api/v1/tags/ HTTP/1.1¶

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)

pyfarm.master.api.tags.schema()[source]¶

Returns the basic schema of Tag

GET /api/v1/tags/schema/ HTTP/1.1¶

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