Rest.li Protocol

{toc:maxLevel=4}

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:

Tutorials
Dynamic Discovery
Request Response API
Rest.li User Guide
- Rest.li Server
- Resources
- Resource Types
- Resource Methods
  - Create
  - Get
  - Update
  - Delete
  - Finders
  - Actions
- Rest.li Client
Projections
Filters
Wire Protocol
Data Schemas
Data
- How Data is Serialized for Transport
- How Data is Represented in Memory
Unstructured Data
Tools
- IDL generation
- Client binding generation
FAQ
- Data FAQ

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Rest.li Protocol

URI Syntax

Content Types

Collection Resources

Collection URIs

Association Resources

assockey syntax

URI template

`{firstkey}{&keys*}`

URI examples

`Complete key: followerID=1&followeeID=3`

Association URIs

Finders

Finder URIs

Actions

Action URIs

URI modifiers

URIs

Response Status Codes

Message Headers

Request Message Body

Single Entity

Batch Create

Batch Update

Partial Update

Batch Partial Update

Response Message Body

Single Entity

List of Entities

Map of Entities

Collection Metadata

Error Response

Complex types

Complex types as keys

Complex types as query parameter values

Clone this wiki locally

Rest.li Protocol

URI Syntax

Content Types

Collection Resources

Collection URIs

Association Resources

assockey syntax

URI template {firstkey}{&keys*}

URI examples Complete key: followerID=1&followeeID=3

Association URIs

Finders

Finder URIs

Actions

Action URIs

URI modifiers

URIs

Response Status Codes

Message Headers

Request Message Body

Single Entity

Batch Create

Batch Update

Partial Update

Batch Partial Update

Response Message Body

Single Entity

List of Entities

Map of Entities

Collection Metadata

Error Response

Complex types

Complex types as keys

Complex types as query parameter values

Clone this wiki locally

URI template

`{firstkey}{&keys*}`

URI examples

`Complete key: followerID=1&followeeID=3`