Rest.li .restspec.json Format

This RESTSpec JSON schema is the interface definition language (IDL) used by Rest.li.

See http://tools.ietf.org/html/draft-zyp-json-schema for explanation of JSON schema notation.

Resources Schema

(this object is used to wrap multiple non-split resources in one .restspec.json)

JSON Schema:

{
  "name" : "ResourcesSchema",
  "properties" : {
    "resources" : {
      "type" : "array",
      "items" : {
        "type" : {"$ref" : "#ResourceSchema" }
      },
      "description" : "list of resources described by this IDL"
    }
  }
}

Resource Schema

JSON schema:

{
  "name" : "ResourceSchema",
  "properties" : {
    "name" : {
      "type" : "string",
      "required" : true,
      "description" : "name of the resource"
    }
    "namespace" : {
      "type" : "string",
      "description" : "namespace of the resource"
    }
    "path" : {
      "type" : "string",
      "required" : true,
      "description" : "URI template for accessing the resource"
    }
    "schema" : {
      "type" : "string",
      "required" : true,
      "description" : "Java-style fully-qualified class name for entities of this resource"
    }
    "collection" : {
      "type" : {"$ref" : "#CollectionSchema" },
      "description" : "details of collection, if this resource is a collection"
    }
    "association" : {
      "type" : {"$ref" : "#AssociationSchema" },
      "description" : "details of association, if this resource is an association"
    }
    "actions-set" : {
      "type" : {"$ref" : "#ActionsSetSchema" },
      "description" : "details of action set, if this resource is an action set"
    }
  }
}

Example:

{
  "name" : "greetings",
  "path" : "/greetings",
  "schema" : "com.linkedin.greetings.api.Greeting",
  "doc" : "A richer \"Hello world\" example, demonstrating a full array of methods, finders and actions",
  "collection" : { ... }
}

Collection Schema

JSON schema:

{
  "name" : "CollectionSchema",
  "properties" : {
    "identifier" : {
      "type" : { "$ref" : "#IdentifierSchema" },
      "required" : true,
      "description" : "details of the identifier (key) for this collection"
    },
    "supports" : {
      "type" : "array",
      "items" : {
         "type" : "string"
      },
      "required" : true,
      "description" : "basic rest.li methods supported by this resource, e.g., create, get, update, delete, batch_get"
    },
    "finders" : {
      "type" : "array",
      "items" : {
        "type" : { "$ref" : "#FinderSchema" }
      },
      "description" : "list of finders supported by this collection"
    },
    "actions" : {
      "type" : "array",
      "items" : {
        "type" : { "$ref" : "#ActionSchema" }
      },
      "description" : "list of actions supported by this collection"
    }
    "entity" : {
      "type" : { "$ref" : "#EntitySchema" }
      "description" : "details on the entities contained in this collection"
    }
  }
}

Example:

"collection" :
{

  “identifier” : { … }

  “supports” : [ “batch_get”, “create”, “delete”, “get”, “update” ],

  “finders” : [ … ]

  “actions” : [ … ]

  “entity” : { … }

}

Identifier Schema

JSON schema:

{
  "name" : "IdentifierSchema",
  "properties" : {
    "name" : {
      "type" : "string",
      "required" : true,
      "description" : "name of the identifier"
    },
    "type" : {
      "type" : "string",
      "required" : true,
      "description" : "avro type of the identifier"
    }
  }
}

Examples:

"identifier" :
{

  “name” : “id”,

  “type” : “long”

}

Finder Schema

JSON Schema:

{
  "name" : "FinderSchema",
  "properties" : {
    "name" : {
      "type" : "string",
      "description" : "name of this finder - not required if this is the default finder"
    },
    "default" : {
      "type" : "boolean",
      "description" : "indicates whether this is the default finder for the resource"
    },
    "parameters" : {
      "type" : "array",
      "items" : { "$ref" : "#ParameterSchema" },
      "description" : "list of query parameters for this finder"
    },
    "metadata" : {
      "type" : { "$ref" : "#MetadataSchema" },
      "description" : "describes the collection-level metadata returned by this finder"
    },
    "assocKey" : {
      "type" : "string",
      "description" : "association key for this finder - only present if this finder takes a single association key"
    },
    "assocKeys" : {
      "type" : "array",
      "items" : {
         "type" : "string"
      },
      "description" : "list of association keys for this finder - only present if this finder takes multiple association keys"
    },
    "doc" : {
      "type" : "string",
      "description" : "documentation for this finder"
    }
  }
}

Examples:

"finder" :
{
  "name" : "search",
  "parameters" : [ ... ]
}

Parameter Schema

JSON schema:

{
  "name" : "ParameterSchema",
  "properties" : {
    "name" : {
      "type" : "string",
      "required" : true,
      "description" : "name of this parameter"
    },
    "type" : {
      "type" : "string",
      "required" : true,
      "description" : "avro type of this parameter"
    },
    "items" : {
      "type" : "string",
      "required" : false,
      "description" : "avro type of this array parameter items"
    },
    "optional" : {
      "type" : "boolean"
      "description" : "indicates whether this parameter is optional. omitted for required parameters"
    }
    "default" : {
      "type" : "string",
      "description" : "indicates the default value for this parameter"
    }
    "doc" : {
      "type" : "string",
      "description" : "documentation for this parameter"
    }
  }
}

Examples:

"parameter" :
{

  “name” : “tone”,

  “type” : “com.linkedin.greetings.api.Tone”,

  “optional” : true

}

Metadata Schema

JSON schema:

{
  "name" : "MetadataSchema",
  "properties" : {
    "type" : {
      "type" : "string",
      "required" : true,
      "description" : "pegasus type of the metadata"
    }
}

Examples:

"metadata" :
{

  “type” : “com.linkedin.greetings.api.SearchMetadata”,

}

Action Schema

JSON schema:

{
  "name" : "ActionSchema",
  "properties" : {
    "name" : {
      "type" : "string",
      "required" : true,
      "description" : "name of this action"
    },
    "parameters" : {
      "type" : "array",
      "items" : { "$ref" : "#ParameterSchema" },
      "description" : "parameters for this action"
    },
    "returns" : {
      "type" : "string",
      "description" : "avro type of this action's return value"
    },
    "throws" : {
      "type" : "array",
      "items" : {
        "type" : "string"
      },
      "description" : "list of exception types thrown by this action"
    }
    "doc" : {
      "type" : "string",
      "description" : "documentation for this action"
    }
  }
}

Examples:

"action" :
{

  “name” : “anotherAction”,

  “doc” : “Deletes all greetings”,

  “parameters” : [ … ]

}

"action" :

{
  "name" : "exceptionTest",
  "throws" : [ "com.linkedin.groups.api.GroupOwnerException" ]
}

Entity Schema

JSON schema:

{
  "name" : "EntitySchema",
  "properties" : {
    "path" : {
      "type" : "string",
      "required" : true,
      "description" : "URI template for accessing this entity"
    },
    "actions" : {
      "type" : "array",
      "items" : { "$ref" : "#ActionSchema" },
      "description" : "list of actions supported by this entity"
    },
    "subresources" : {
      "type" : "array",
      "items" : { "$ref" : "#ResourceSchema" },
      "description" : "list of subresources accessible via this entity"
    }
  }
}

Examples:

"entity" :
{

  “path” : “/greetings/{id}”,

  “actions” : [ … ]

}

Association Schema

JSON schema:

{
  "name" : "AssociationSchema",
  "properties" : {
    "assocKeys" : {
      "type" : "array",
      "items" : { "$ref" : "#AssocKeySchema" },
      "required" : true,
      "description" : "list of association keys for this association"
    },
    "supports" : {
      "type" : "array",
      "items" : {
        "type" : "string"
      },
      "required" : true,
      "description" : "list of rest.li methods supported by this association, e.g., get, update, delete, batch_get"
    },
    "finders" : {
      "type" : "array",
      "items" : { "$ref" : "#FinderSchema" },
      "description" : "list of finders supported by this association"
    },
    "actions" : {
      "type" : "array",
      "items" : { "$ref" : "#ActionSchema" },
      "description" : "list of actions supported by this association"
    }
    "entity" : {
      "type" : { "$ref" : "#EntitySchema" },
      "required" : true,
      "description" : "details of the entity provided by this association"
    }
  }
}

Examples:

"association" :
{

  “assocKeys” : [ … ],

  “supports” : [ “batch_get”, “get”, “update” ],

  “finders” : [ … ],

  “entity” : { … }

}

AssocKey Schema

JSON schema:

{
  "name" : "AssocKeySchema",
  "properties" : {
    "name" : {
      "type" : "string",
      "required" : true,
      "description" : "name of association key"
    },
    "type" : {
      "type" : "string",
      "required" : true,
      "description" : "avro type of association key"
    },
  }
}

Examples:

"assocKey" :
{

  “name” : “followerID”,

  “type” : “long”

}

Actions Set Schema

JSON schema:

{
  "name" : "ActionsSetSchema",
  "properties" : {
    "actions" : {
      "type" : "array",
      "items" : { "$ref" : "#ActionSchema" },
      "required" : true,
      "description" : "list of actions supported by this action set"
    }
  }
}

Examples:

"actions-set" :
{
  "actions" : [ ... ]
}

Complete Examples

Greetings example:

{
  "name" : "greetings",
  "path" : "/greetings",
  "schema" : "com.linkedin.greetings.api.Greeting",
  "doc" : "A richer \"Hello world\" example, demonstrating a full array of methods, finders and actions",
  "collection" : {
    "identifier" : {
      "name" : "id",
      "type" : "long"
    },
    "supports" : [ "batch_get", "create", "delete", "get", "update" ],
    "finders" : [ {
      "name" : "search",
      "parameters" : [ {
        "name" : "tone",
        "type" : "com.linkedin.greetings.api.Tone",
        "optional" : true
      } ]
    } ],
    "actions" : [ {
      "name" : "anotherAction",
      "doc" : "Deletes all greetings",
      "parameters" : [ {
        "name" : "bitfield",
        "type" : {
          "type" : "array",
          "items" : "boolean"
        }
      }, {
        "name" : "request",
        "type" : "com.linkedin.groups.api.TransferOwnershipRequest"
      }, {
        "name" : "someString",
        "type" : "string"
      }, {
        "name" : "stringMap",
        "type" : {
          "type" : "map",
          "values" : "string"
        }
      } ]
    }, {
      "name" : "exceptionTest",
      "throws" : [ "com.linkedin.groups.api.GroupOwnerException" ]
    } ],
    "entity" : {
      "path" : "/greetings/{id}",
      "actions" : [ {
        "name" : "anotherAction",
        "doc" : "Deletes all greetings",
        "parameters" : [ {
          "name" : "bitfield",
          "type" : {
            "type" : "array",
            "items" : "boolean"
          }
        }, {
          "name" : "request",
          "type" : "com.linkedin.groups.api.TransferOwnershipRequest"
        }, {
          "name" : "someString",
          "type" : "string"
        }, {
          "name" : "stringMap",
          "type" : {
            "type" : "map",
            "values" : "string"
          }
        } ]
      }, {
        "name" : "exceptionTest",
        "throws" : [ "com.linkedin.groups.api.GroupOwnerException" ]
      }, {
        "name" : "someAction",
        "parameters" : [ {
          "name" : "a",
          "type" : "int",
          "default" : "1"
        }, {
          "name" : "b",
          "type" : "string",
          "default" : "default"
        }, {
          "name" : "c",
          "type" : "com.linkedin.groups.api.TransferOwnershipRequest",
          "optional" : true
        }, {
          "name" : "d",
          "type" : "com.linkedin.groups.api.TransferOwnershipRequest"
        }, {
          "name" : "e",
          "type" : "int"
        } ],
        "returns" : "com.linkedin.greetings.api.Greeting"
      } ]
    }
  }
}