Skip to content

Latest commit

 

History

History
236 lines (205 loc) · 8.62 KB

README.md

File metadata and controls

236 lines (205 loc) · 8.62 KB
Raw

dobby_rest

RESTish interface to dobby, the graph store

###Requirements

  1. dobby.
  2. Erlang R17

###Building

  1. make compile
  2. make generate

###Running

  1. dobby must be running
  2. rel/dobby_rest/bin/dobby_rest console

Note that some request errors are reported to the dobby_rest console. Check the logs if dobby_rest returns status 500 to the REST client.

###Testing You can use the Google Chrome extension Postman to test the REST calls. Import the dobby_rest.json collection for some examples.

###HTTP response codes

Response code Description
200 Success
201 Successfully created resource
204 Successfully deleted resource
404 Not Found
422 POST request malformed/incomplete
500 Server Error

###Identifiers

Description URI Method Request Body Response Body
Get identifier details /identifier/identifier_name GET n/a Example 1
Create identifier /identifier/identifier_name POST Example 2 true/false
Delete identifier /identifier/identifier_name DELETE n/a true/false
  • In the response object, the identifier value is URL encoded.
  • Deleting a identifier will remove associated links.

####Example 1 - identifier JSON response object:

{
    "identifier":"name2",
    "metadata":{
       "key":{
         "value":1,
         "timestamp":"2015-05-01T23:22:14Z",
         "publisher_id":"dobby_rest"
       },
       "key2":{
         "value":"2",
         "timestamp":"2015-05-01T23:22:14Z",
         "publisher_id":"dobby_rest"
       }
    }
}

####Example 2 - create identifier JSON request body

{"metadata":{"key":1,"key2":"2"}}

###Links

Description URI Method Request Body Response Body
create link /link/id1/id2 POST Example 3 true/false
get link /link/id1/id2 GET n/a Example 4
delete link /link/id1/id2 DELETE n/a true/false
  • Missing vertices will be created when adding a link.
  • Links are not directed so link names are symmetric. That is idA/idB is the same as idB/idA.

####Example 3 - create link request body

{
  "metadata":{
    "ip":"10.151.1.68"
  }
}

####Example 4 - link JSON response object

{
  "link":"id1/id2",
  "metadata":{
    "ip":{
      "value":"10.151.1.68",
      "timestamp":"2015-06-04T02:51:32Z",
      "publisher_id":"dobby_rest"
  }
}

###Identifier Metadata

Description URI Method Request Body Response Body
get identifier metadata property /identifier/identifier_name/metadata/ip GET n/a "1"
add or update identifier metadata /identifier/identifier_name/metadata/ip POST "2.2.2.2" true/false
remove identifier metadata /identifier/identifier_name/metadata/ip DELETE n/a true/false

###Link Metadata

Description URI Method Request Body Response Body
get link metadata property /link/id1/id2/metadata/creation_datetime GET n/a "2014-07-16T19:20:30+01:00"
add link metadata /link/id1/id2/metadata/key POST "value" true/false
remove link metadata /link/id1/id2/metadata/key DELETE n/a true/false

###Search

Description URI Method Request Body Response Body
search on identifier /identifier/vname1%2F2/search POST Example 6 Example 8

###Example 6 - search request JSON body

{
  "max_depth":1,
  "traversal":"depth",
  "max_size":100,
  "match_metadata":{
      "type":["IPV4", "IPV6"]
  },
  "match_links":{
    "type":"IP-MAC"
  }
  "results_filter":["capabilities"],
  "match_terminal":{
    "type":"device"
  }
}
Parameter Description
max_depth maximum search depth from starting identifier (e.g., vname1)
traversal graph traversal algorithm (depth for depth first or breadth for breadth first)
max_size maximum number of identifiers in the result set (not implemented)
match_metadata only follow links from identifiers with metadata matching these key/value pairs. The identifier's metadata must match all of the key/value pairs. If not given or all (instead of a list) then all links are followed.
match_links only follow links with metadata matching these key/value pairs. The link's metadata must match all of the key/value pairs. If not given or all (instead of a list) then all links are followed.
match_terminal stop the search when the identifer has metadata matching these key/value pairs. The identifier's metadata mush match all of the key/value pairs. The identifier and link is included in the result. If not given or none (instead of a list) then the search does not terminate by with a metadata match.
results_filter list of metadata keys to include in the metadata in the results. If not given or all (instead of a list), then all of the metadata is included.
match_path Describes a desired path in the graph to match against. All identifiers in matching paths are included in the results. The desired path is a list of elements indicating metadata to match against of the link or of the identifier in the path. The desired path may be a mix of identifiers and links. match_links and match_metadata may be used in conjunction with match_path in which case the match_path is checked after the other matches. See Example 8.
  • For match_metadata, match_links, and match_terminal the value of the key/value match pair may be a single element or a list. If the value is a single element then a match occurs when the metadata value in dobby matches the single element. If the value in the key/value match pair is a list then a match occurs when the metadata avlue is dobby matches one of the elements of the list.
  • The Result is a list of identifiers and links.
  • In the response object, the identifier value and the identifiers in the link value are URL encoded.

###Example 7 - match_path example

{
  "max_depth":10,
  "traversal":"depth",
  "match_path":[
    [
     {"element":"identifier","metadata":{"type":"of_switch"}},
     {"element":"link","metadata":{"type":"port_of"}},
     {"element":"identifier","metadata":{"type":"of_port"}},
     {"element":"link","metadata":{"type":"connected_to"}},
     {"element":"identifier","metadata":{"type":"of_port"}},
     {"element":"link","metadata":{"type":"port_of"}},
     {"element":"identifier","metadata":{"type":"of_switch"}}
    ],
    [
     {"element":"identifier","metadata":{"type":"of_switch"}},
     {"element":"identifier","metadata":{"type":"of_port"}},
     {"element":"link","metadata":{"type":"connected_to"}},
     {"element":"identifier","metadata":{"type":"endpoint"}}
    ]
  ]
}

Looks for two different paths. The first path is a connection between two switches (of_switch, linked via a port_of to an of_port, the of_port linked via a connected_to to another of_port, linked via a port_of to an of_switch), and between a switch and an endpoint (of_switch linked by an unspecified link type to an of_port linked via a connected_to to an endpoint).

###Example 8 - search response JSON

[
    {
        "identifiers":[
            {
              "identifier":"vname1%2F2",
              "metadata":{
                "type":{
                  "value":"resource",
                   "timestamp":"2015-05-01T23:22:14Z",
                   "publisher_id":"dobby_rest"
                },
                "ip":{
                  "value":"9.9.9.9"
                   "timestamp":"2015-05-01T23:22:14Z",
                   "publisher_id":"dobby_rest"
                }
              }
            },
            {
              "identifier":"vname2",
              "metadata":{
                "type":{
                  "value":"resource",
                   "timestamp":"2015-05-01T23:22:14Z",
                   "publisher_id":"dobby_rest"
                },
                "ip":{
                  "value":"8.8.8.8"
                   "timestamp":"2015-05-01T23:22:14Z",
                   "publisher_id":"dobby_rest"
                }
              }
            }
        ],
        "links":[
            {
              "link":"vname1%2F2/vname2"
              "metadata":{
                "type":{
                  "value":"connection"
                   "timestamp":"2015-05-01T23:22:14Z",
                   "publisher_id":"dobby_rest"
                }
              }
            }
        ]
]