Skip to content

Rexster Mime Types

Jump to bottom
spmallette edited this page May 19, 2012 · 7 revisions

Mime types are used in the REST API to let consumers choose the format of the data they wish to receive (via the Accept header), as well as to explain to Rexster the type of content being sent (via the Content-Type header).

Accept Header

There are three formats that may be set on the Accept header.

  • application/json
  • application/vnd.rexster-v1+json
  • application/vnd.rexster-typed-v1+json

If the Accept header is not specified, Rexster will return application/json in its response. Both application/vnd.rexster-v1+json and application/vnd.rexster-typed-v1+json are considered custom types and can be generally applied to all requests with the exception of Extension requests, as they are capable of exposing their own specific content types.

While all three types are JSON formats, application/vnd.rexster-v1+json and application/vnd.rexster-typed-v1+json provide additional information in their responses which may be important to consumers. The application/vnd.rexster-v1+json type contains link information regarding configured and available extensions, specifically for the graph, vertex, and edge resource and the application/vnd.rexster-typed-v1+json type is the same but also includes property data type information embedded within the returned JSON.

Examples

This first request does not specify the Accept header and therefore Rexster simply returns application/json.

curl -v http://localhost:8182/graphs/tinkergraph/edges/11
{
    "version": "*.*",
    "results": {
        "weight": 0.4000000059604645,
        "_id": "11",
        "_type": "edge",
        "_outV": "4",
        "_inV": "3",
        "_label": "created"
    },
    "queryTime": 1.225442
}

The following request to the same resource uses application/vnd.rexster-v1+json and Rexster therefore responds with the same result as above, but includes the list of configured extensions.

curl -v -H "Accept:application/vnd.rexster-v1+json" http://localhost:8182/graphs/tinkergraph/edges/11
{
    "version": "*.*",
    "results": {
        "weight": 0.4000000059604645,
        "_id": "11",
        "_type": "edge",
        "_outV": "4",
        "_inV": "3",
        "_label": "created"
    },
    "queryTime": 0.363026,
    "extensions": [
        {
            "title": "tp:gremlin",
            "op": "GET",
            "description": "evaluate an ad-hoc Gremlin script for an edge.",
            "name": "gremlin",
            "parameters": [
                {
                    "description": "displays the properties of the elements with their native data type (default is false)",
                    "name": "rexster.showTypes"
                },
                {
                    "description": "an array of element property keys to return (default is to return all element properties)",
                    "name": "rexster.returnKeys"
                },
                {
                    "description": "start index for a paged set of data to be returned",
                    "name": "rexster.offset.start"
                },
                {
                    "description": "end index for a paged set of data to be returned",
                    "name": "rexster.offset.end"
                },
                {
                    "description": "the Gremlin script to be evaluated",
                    "name": "script"
                }
            ],
            "href": "http://localhost:8182/graphs/tinkergraph/edges/11/tp/gremlin",
            "namespace": "tp"
        },
        {
            "title": "tp:gremlin",
            "op": "POST",
            "description": "evaluate an ad-hoc Gremlin script for an edge.",
            "name": "gremlin",
            "parameters": [
                {
                    "description": "displays the properties of the elements with their native data type (default is false)",
                    "name": "rexster.showTypes"
                },
                {
                    "description": "an array of element property keys to return (default is to return all element properties)",
                    "name": "rexster.returnKeys"
                },
                {
                    "description": "start index for a paged set of data to be returned",
                    "name": "rexster.offset.start"
                },
                {
                    "description": "end index for a paged set of data to be returned",
                    "name": "rexster.offset.end"
                },
                {
                    "description": "the Gremlin script to be evaluated",
                    "name": "script"
                }
            ],
            "href": "http://localhost:8182/graphs/tinkergraph/edges/11/tp/gremlin",
            "namespace": "tp"
        }
    ]
}

This final request in the example set uses application/vnd.rexster-typed-v1+json and Rexster therefore responds with the same result as above, but includes embedded data types within the JSON itself.

curl -v -H "Accept:application/vnd.rexster-typed-v1+json" http://localhost:8182/graphs/tinkergraph/edges/11
{
    "version": "*.*",
    "results": {
        "weight": {
            "type": "float",
            "value": 0.4000000059604645
        },
        "_id": "11",
        "_type": "edge",
        "_outV": "4",
        "_inV": "3",
        "_label": "created"
    },
    "queryTime": 0.981574,
    "extensions": [
        {
            "title": "tp:gremlin",
            "op": "GET",
            "description": "evaluate an ad-hoc Gremlin script for an edge.",
            "name": "gremlin",
            "parameters": [
                {
                    "description": "displays the properties of the elements with their native data type (default is false)",
                    "name": "rexster.showTypes"
                },
                {
                    "description": "an array of element property keys to return (default is to return all element properties)",
                    "name": "rexster.returnKeys"
                },
                {
                    "description": "start index for a paged set of data to be returned",
                    "name": "rexster.offset.start"
                },
                {
                    "description": "end index for a paged set of data to be returned",
                    "name": "rexster.offset.end"
                },
                {
                    "description": "the Gremlin script to be evaluated",
                    "name": "script"
                }
            ],
            "href": "http://localhost:8182/graphs/tinkergraph/edges/11/tp/gremlin",
            "namespace": "tp"
        },
        {
            "title": "tp:gremlin",
            "op": "POST",
            "description": "evaluate an ad-hoc Gremlin script for an edge.",
            "name": "gremlin",
            "parameters": [
                {
                    "description": "displays the properties of the elements with their native data type (default is false)",
                    "name": "rexster.showTypes"
                },
                {
                    "description": "an array of element property keys to return (default is to return all element properties)",
                    "name": "rexster.returnKeys"
                },
                {
                    "description": "start index for a paged set of data to be returned",
                    "name": "rexster.offset.start"
                },
                {
                    "description": "end index for a paged set of data to be returned",
                    "name": "rexster.offset.end"
                },
                {
                    "description": "the Gremlin script to be evaluated",
                    "name": "script"
                }
            ],
            "href": "http://localhost:8182/graphs/tinkergraph/edges/11/tp/gremlin",
            "namespace": "tp"
        }
    ]
}

Content-Type Header

There are several formats that may be set on the Content-Type header when doing a POST, PUT, or DELETE operation.

  • application/x-www-form-urlencoded
  • application/json
  • application/vnd.rexster-v1+json
  • application/vnd.rexster-typed-v1+json

Rexster also offers the flexibility of performing those operations directly on the URI.

Rexster’s will use embedded typing when the Content-Type is set to application/x-www-form-urlencoded, application/vnd.rexster-typed-v1+json, or is a URI mapping. If the Content-Type is set to application/json or application/vnd.rexster-v1+json it will use native JSON data types.

Examples

The following curl command POSTs a new vertex to a URI:

curl -v -X POST "http://localhost:8182/graphs/emptygraph/vertices?x=(integer,123)&y=(s,123)"

and Rexster associates each property with the correct data type:

{
    "version": "*.*",
    "results": {
        "y": "123",
        "x": 123,
        "_id": "0",
        "_type": "vertex"
    },
    "queryTime": 1.871345
}

The following is the same POST without the data type formatting:

curl -v -X POST "http://localhost:8182/graphs/emptygraph/vertices?x=123&y=123"

and Rexster just assumes that the property values are both strings:

{
    "version": "*.*",
    "results": {
        "y": "123",
        "x": "123",
        "_id": "0",
        "_type": "vertex"
    },
    "queryTime": 1.871345
}

Now consider the POST of application/json using the same parameters:

curl -v -X POST -H "Content-Type:application/json" -d '{"y":"123","x":123}' "http://localhost:8182/graphs/emptygraph/vertices"

In this case, Rexster uses the native JSON data types.

{
    "version": "*.*",
    "results": {
        "y": "123",
        "x": 123,
        "_id": "0",
        "_type": "vertex"
    },
    "queryTime": 0.5959555
}

The next examples demonstrates what happens an embedded-type request with a Content-Type of application/json is POSTed:

curl -v -X POST -H "Content-Type:application/json" -d '{"y":"(s,123)","x":"(i,123)"}' "http://localhost:8182/graphs/emptygraph/vertices"

Note below how the embedded-types are not parsed and the data is just stored literally:

{
    "version": "*.*",
    "results": {
        "y": "(s,123)",
        "x": "(i,123)",
        "_id": "3",
        "_type": "vertex"
    },
    "queryTime": 0.949773
}

To get Rexster to parse those types the Content-Type must be set to application/vnd.rexster-typed-v1+json as in:

curl -v -X POST -H "Content-Type:application/vnd.rexster-typed-v1+json" -d '{"y":"(s,123)","x":"(i,123)"}' "http://localhost:8182/graphs/emptygraph/vertices"
{
    "version": "*.*",
    "results": {
        "y": "123",
        "x": 123,
        "_id": "4",
        "_type": "vertex"
    },
    "queryTime": 1.082941
}
Clone this wiki locally