Skip to content

Latest commit

 

History

History
753 lines (679 loc) · 13.7 KB

REST-API.md

File metadata and controls

753 lines (679 loc) · 13.7 KB
Raw

Rest API offered by our server

Possible parameters' descriptions

Parameter Type Format Represents
from, to, of, id string zone_id:name ID of a vertex
type, name string Some value
permissions string 11010 Permissions set on given edge
trace string (optional) Globally unique identifier of set of events about the same operation on the graph
successive boolean I have no idea, but Kamil has it
enabled boolean Stores info whether enable or disable some setting

Manipulating Vertices

Create new vertex

Path /graph/vertices
Method POST
Params
  • type
  • name
Body void
Return type void

Get all vertices

Path /graph/vertices/listing
Method GET
Params none
Body void
Return type {"users": list(string), "groups": list(string), "spaces": list(string), "providers": list(string)}

Get details of vertex by ID

Path /graph/vertices/details
Method GET
Params
  • id
Body void
Return type {"id": string, "type": string, "name": string, "zone": string}

Delete vertex

Path /graph/vertices/delete
Method POST
Params
  • id
Body void
Return type void

Bulk vertex request

Path /graph/vertices/bulk
Method POST
Params none
Body {"vertices": ["type1/name1", "type2/name2", ..]}
Return type void

Manipulating Edges

Create edge

Path /graph/edges
Method POST
Params
  • from
  • to
  • permissions
  • trace: optional
  • successive
Body void
Return type void

Set permissions

Path /graph/edges/permissions
Method POST
Params
  • from
  • to
  • permissions
  • trace: optional
  • successive
Body void
Return type void

Delete edge

Path /graph/edges/delete
Method POST
Params
  • from
  • to
  • trace: optional
  • successive
Body void
Return type void

Bulk create-edges request

Path /graph/edges/bulk
Method POST
Params none
Body {"sourceZone": string, "destinationZone": string, "successive": boolean, "edges": ["fromName/toName/permissions/trace", ..]}
where trace can be empty string
Return type void

Basic queries about structure of the graph (edges)

Check if edge exists

Path /is_adjacent
Method POST
Params
  • from
  • to
Body void
Return type boolean

Get permissions of the edge

Path /permissions
Method POST
Params
  • from
  • to
Body void
Return type string

Get parents of given vertex

Path /list_adjacent
Method POST
Params
  • of
Body void
Return type list(string)

Get children of given vertex

Path /list_adjacent_reversed
Method POST
Params
  • of
Body void
Return type list(string)

Meta Info - Server Config

Health check to determine if server is running

Path /healthcheck
Method GET
Params none
Body void
Return type void

Index ready - checks if there are any waiting or currently processed events in this zone

Path /index_ready
Method GET
Params none
Body void
Return type boolean

Enable/Disable indexation

Path /indexation
Method PUT
Params none
Body enabled: boolean
Return type void

Enable/Disable instrumentation

Path /instrumentation
Method PUT
Params none
Body enabled: boolean
Return type void

Check if instrumentation is enabled

Path /instrumentation
Method GET
Params none
Body void
Return type boolean

Dependent Zones - check if needed zones are running and to get stats about them

DEPRECATED: its sole purpose is for Kamil's integration tests

Path /dependent_zones
Method POST
Params none
Body list(string)
Return type {"zones": list(string)}

Load simulation

Run batch of operations

Path /simulate_load
Method POST
Params none
Body {"ops": [{..}, .., {..}]}
Where inner objects have fields <"t" - operation type {"a", "r", "p"}, "f" - from, "to" - to, "p" - permissions, "tr" - trace>
Return type void

Main Functionality: Queries about relations between any vertices in the graph

ISO-8601 Format

In responses described in this section there is a field called "duration", that stores time needed to execute the request. That duration is stored as string in format given by ISO-8601 standard, described here.

For the needs of our application we can assume that duration is smaller than 1 minute. In that case, string looks like this: "PTxS", where x is a floating-point number with 6 decimal places, describing number of seconds (the integer part) and microseconds (the fractional part).

WARNING: in current state our server doesn't send times longer than 24 hours.

Check existence of path (is 'from' effective child of 'to'?)

Path /naive/reaches
/indexed/reaches
Method POST
Params
  • from
  • to
Body void
Return type {"duration": Time-ISO-8601, "reaches": boolean}

Get effective permissions 'from' possesses about 'to'

Path /naive/effective_permissions
/indexed/effective_permissions
Method POST
Params
  • from
  • to
Body void
Return type {"duration": Time-ISO-8601, "effectivePermissions": string}

List effective children of given vertex

Path /naive/members
/indexed/members
Method POST
Params
  • of
Body void
Return type {"duration": Time-ISO-8601, "effectivePermissions": list(string)}

Event propagation

Single event

Path /events
Method POST
Params
  • id; *this is id of the vertex event is posted 'on'
Body {"type": string, "trace": string, "sender": string, "originalSender": string, "effectiveVertices": ["id1", ..]}
Return type void

Bulk of events

Path /events/bulk
Method POST
Params none
Body {"messages": [{"vn": string, "e": Event}, ..]}
Event format is described in "Single event" section
Return type void

Get events stats

Path /events/stats
Method GET
Params none
Body void
Return type {"processing": int, "processingNanos": double, "processingByType": {"user": int, ..}, "queued": int, "outbox": int, "total": long, "load1": double, "load5": double, "long15": double}