Skip to content

Rest.li Protocol

Jump to bottom
jpbetz edited this page Nov 30, 2012 · 3 revisions

URI Syntax

URIs are described using URI templates as defined in the draft spec: [http://tools.ietf.org/html/draft-gregorio-uritemplate-07]

Content Types

The content type of pegasus data is {{application/json}}.

Collection Resources

The URI templates below assume variables with types as follows:


collection : simple string or "complex key"
entity_id : simple string
ids : list
finder : simple string
params : associative array

Collection URIs

|| Resource || URI Template || Example || Method || Semantics || | Collection | /{collection} | /statuses | POST | CREATE - creates an entity in the collection | | Collection | /{collection}/{entity_id} | /statuses/1 | GET | READ - returns the referenced entity | | Collection | /{collection}/{entity_id} | /statuses/1 | PUT | UPDATE - updates the referenced entity | | Collection | /{collection}/{entity_id} | /statuses/1 | POST | PARTIAL UPDATE - partially updates the referenced entity | | Collection | /{collection}/{entity_id} | /statuses/1 | DELETE | DELETE - deletes the referenced entity | | Collection | /{collection}?{ids} | /statuses?ids=1,2,3 | GET | BATCH_GET - returns a map containing the referenced entities | | Collection | /{collection}?q={finder} | /statuses?q=search | GET | FINDER - returns a list containing entities satisfying the query | | Collection | /{collection}?q={finder}{&params*} | /statuses?q=search&keywords=linkedin | GET | FINDER - returns a list containing entities satisfying the query |

Association Resources

Associations contain entities referenced by compound keys, referred to here as assockeys

The URI templates below assume variables with types as follows:


firstkey : associative array containing a single element
keys : associative array
association : simple string
assockey : simple string conforming to the assockey syntax described below
assockeys : list of strings conforming to the assockey syntax
finder : simple string
params : associative array

assockey syntax

URI template

{firstkey}{&keys*}
URI examples

Complete key:
followerID=1&followeeID=3

Partial key:
followerID=1

Association URIs

|| Resource || URI Template || Example || Method || Semantics || | Association | /{association}/{+assockey} | /follows/followerID=1&followeeID=1 | GET | READ - returns the referenced association entity | | Association | /{association}/{+assockey} | /follows/followerID=1&followeeID=1 | PUT | UPDATE - updates the referenced association entity | | Association | /{association}/{+assockey} | /follows/followerID=1&followeeID=1 | DELETE | DELETE - deletes the referenced association entity | | Association | /{association}/{+assockeys*} | /follows/?ids=followerID%3D1%26followeeID%3D1&ids=followerID%3D1%26followeeID%3D3&ids=followerID%3D1%26followeeID%3D2 \ Note: followerID%3D1%26followeeID%3D1 unescapes to followerID=1&followeeID=1 | GET | BATCH_GET - returns a map containing the referenced association entities | | Association | /{association}?q={finder} | /follows?q=search | GET | FINDER - returns a list containing entities satisfying the query | | Association | /{association}?q={finder}{&params*} | /follows?q=followers&userID=1 | GET | FINDER - returns a list containing entities satisfying the query | | Association | /{association}/{+assockey} | /follows/followerID=1?q=other | GET | FINDER - returns a list containing the entities satisfying the query | | Association | /{association}/{+assockey}?q={finder}{&params*} | /follows/followerID=1?q=other&someParam=value | GET | FINDER - returns a list containing the entities satisfying the query |

Finders

The URI templates below assume variables with types as follows:


finder : simple string identifying a finder

Finder URIs

|| Resource || URI Template || Example || Method || Semantics || | Collection, Association, ActionSet | {resource}?q={finder} | /accounts?q=keywordSearch | GET | invokes the specified finder |

Actions

The URI templates below assume variables with types as follows:


action : simple string

Action URIs

|| Resource || URI Template || Example || Method || Semantics || | Collection, Association, ActionSet | {resource}?action={action} | /accounts?action=register | POST | invokes the specified action |

URI modifiers

The URI templates below assume variables with types as follows:


finder_uri : simple string ...
base_uri : simple string generated via one of the uri templates above
start : simple string
count : simple string
fields : list

URIs

|| Feature || Base URI Type || URI Template || Example || | Paging | Finder | {+finder_uri}{&start,count} | /statuses?q=search&start=0&count=10 | | Projection | Get, BatchGet, Finder | {+base_uri}{&fields} | /groups?q=emailDomain&fields=locale,state | | Schema Return | Any | {+base_uri}&metaDesc | | | Links | Any | {+base_uri}&metaLinks | |

Response Status Codes

Status codes should be interpreted according to the HTTP specification [http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html]

Common status codes used in rest.li:

  • 200 OK
  • 201 Created
  • 204 No Content
  • 400 Bad Request
  • 404 Not Found
  • 405 Method Not Allowed
  • 500 Internal Server Error

Message Headers

|| Message Type || Header || Semantics || Notes || | Response | X-LinkedIn-Type | indicates the RecordTemplate type of the JSON entity in the message body. | X-LinkedIn-Type values are Java-style class names. | | Response | X-LinkedIn-Sub-Type | indicates the RecordTemplate type of contained JSON entities in the message body, in cases where the body is a map or list. | X-LinkedIn-Sub-Type values are Java-style class names. | | Response | X-LinkedIn-Error-Response | indicates whether the message body contains a JSON-serialized ErrorResponse object | The header value is set to "true" when an error response is returned. The header is omitted otherwise. | | Response | X-LinkedIn-Id | indicates the id assigned by the server to a new entity created in a collection. | set on response messages resulting from a successful POST request to create an entity. The header value is set to the entity id, represented as a string | | Response | Location | indicates the URI of a new entity created in a collection. | Location is set on response messages resulting from a successful POST request to create an entity. The header value is set to a URI referencing the newly created entity | | Response | Content-Type | | The Content-Type is always set to "application/json" | | Request | X-RestLi-Method | Set whenever content is POSTed. Can be "GET_ALL", "GET", "BATCH_GET", "CREATE", "BATCH_CREATE", "UPDATE", "PARTIAL_UPDATE", "DELETE", "BATCH_DELETE", "ACTION", "FINDER", "BATCH_PARTIAL_UPDATE" | Is only required for "BATCH_CREATE", "BATCH_PARTIAL_UPDATE", all other method types can be inferred by a RestLi server from the URI string and HTTP Method. |

Request Message Body

Single Entity

Single entities are sent as the JSON serialized DataMap representing that entity. The {{"Content-Type: application/json"}} header may be included for PUT and POST requests, if omitted, the server will assume the request is content type is {{"application/json"}}.

Create:


POST /widgets
Content-Type: application/json

{"widgetName":"Lever"}

Read:


GET /widgets/1

Update:


PUT /widgets/1
Content-Type: application/json

{"widgetName":"Lever"}

Delete:


DELETE /widgets/1

Batch Create

A DataMap with field

  • "elements": A JSON array of the resources to batch create/update and the objects are the json serialized values of each resource to create.

E.g.


POST /widgets HTTP/1.0
Content-Type: application/json
X-RestLi-Method: BATCH_CREATE

{
  "elements": [
    {"widgetName":"Ratchet"},
    {"widgetName":"Cog"}
  ]
}

Note: Batch create requests must include the HTTP Header: 

X-RestLi-Method: BATCH_CREATE

Batch Update

A DataMap with field

  • "entities": A JSON serialized map where the keys are keys of the resources to update and the objects are the json serialized replacement values of each resource to update.

E.g.


PUT /widgets?ids=1&ids=2 HTTP/1.0
Content-Type: application/json
X-RestLi-Method: BATCH_UPDATE

{
  "entities": {
    "1": {"widgetName":"Trebuchet"},
    "2": {"widgetName":"Gear"}
   }
}

Partial Update

Partial update is a set of operations on data object, which is also instance of DataMap. Operations are expressed using fields with reserved word names. Every operation relates to the object that contains it i.e. it's parent. Following sections describe all currently supported operations. See [ENGS:Partial Update] for details.

E.g.


POST /widgets/1 HTTP/1.0
Content-Type: application/json

{
  "patch": {
    "$set": {
      "name": "John",
      "address": {
        "street": "10th",
        "city": "Sunnyvale"
      }
    }
}

Batch Partial Update

See Partial Update and Batch Update above for details, here the two are combined.

E.g.


POST /widgets?ids=1&ids=2 HTTP/1.0
Content-Type: application/json
X-RestLi-Method: BATCH_PARTIAL_UPDATE

{
  "entities": {
    "1": {"patch": { "$set": { "name":"Sam"}}}
    "2": {"patch": { "$delete": { "name":"John"}}}
   }
}

Response Message Body

Single Entity

Single entities are returned as the JSON serialized DataMap representing that entity

List of Entities

Lists of entities are returned in a com.linkedin.rest.CollectionResponse wrapper

CollectionResponse fields:

  • "elements" : JSON serialized list of entity types
  • (optional) "paging" : JSON serialized CollectionMetadata object

E.g.


{
  "elements: [
    { "id": 1, "message": "Good morning!", "tone": "FRIENDLY" }
    // ...
  ],
  "paging": {
    "count": 10,
    "links": [
      "href": "/greetings?count=10&start=10&q=search",
      "rel": "next",
      "type": "application/json"
    ],
    "start": 0
  }
}

Map of Entities

Maps of entities are returned in a com.linkedin.rest.BatchResponse wrapper

BatchResponse fields:

  • "results" : JSON object containing name/value pairs ** name is the string value of each map key ** value is the JSON serialized entity for each map value

Collection Metadata


{"type":"record",
 "name":"CollectionMetadata",
 "namespace":"com.linkedin.common.rest",
 "doc":"Metadata and pagination links for this collection",
 "fields":[
 {
   "name":"start",
   "type":"int",
   "doc":"The start index of this collection"
 },{
   "name":"count",
   "type":"int",
   "doc":"The number of elements in this collection segment"
 },{
   "name":"total",
   "type":"int",
   "doc":"The total number of elements in the entire collection (not just this segment)",
   "default":0
 },{
   "name":"links",
   "type":{
     "type":"array",
     "items":{
       "type":"record",
       "name":"Link",
       "doc":"A atom:link-inspired link",
       "fields":[
       {
         "name":"rel",
         "type":"string",
         "doc":"The link relation e.g. 'self' or 'next'"
       },{
         "name":"href",
         "type":"string",
         "doc":"The link URI"
       },{
         "name":"type",
         "type":"string",
         "doc":"The type (media type) of the resource"
       }]
     }
   },
   "doc":"Previous and next links for this collection"
}]}

Error Response


{
  "type":"record",
  "name":"ErrorResponse",
  "namespace":"com.linkedin.common.rest",
  "doc":"A generic ErrorResponse",
  "fields":[
  {
    "name":"status",
    "type":"int",
    "doc":"The HTTP status code"
  },{
    "name":"serviceErrorCode",
    "type":"int",
    "doc":"An service-specific error code (documented in prose)"
  },{
    "name":"message",
    "type":"string",
    "doc":"A human-readable explanation of the error"
  },{
    "name":"exceptionClass",
    "type":"string",
    "doc":"The FQCN of the exception thrown by the server (included the case of a server fault)"
  },{
    "name":"stackTrace",
    "type":"string",
    "doc":"The full (??) stack trace (included the case of a server fault)"
  }]
}

Complex types

Complex types as keys

When DataMaps (any pegasus record type as defined in a .pdsc file) are used as keys, the are represented as a string of the form:

path1=value1&path2=value2&...pathN=valueN

Where a path specifies a location of a data element in a complex data type. For example,


{
  "key": {
    "x": [
      "a1",
      "a2"
    ],
    "y": 123,
    "key.with.dots": "val"
  }
}

Is represented in a URI as:


key.x[0]=a1&key.x[1]=a2&key.y=123&key~2Ewith~2Edots=val

Where the chars '.[]' are "~ encoded" to their ascii values. This encoding is the same as "% encoding" except that the escape char is '~' and the only reserved chars are '.[]'.

. -> ~2E, [ -> ~5B, ] -> ~5D, ~ -> ~7E

Complex types as query parameter values

??

Quick Access:

Clone this wiki locally