CPHL, or the Cross-Platform Hypertext Language is a hypertext specification for RESTful APIs. CPHL is based on HAL, but is designed to allow for greater flexibility, transmission of additional information, and empowerment of resource specific code on demand.
It is also designed to be action driven, rather than resource driven. This means that a resource may be included multiple times if necessary (ie edit, delete), but described by it's title, description, and the methods it utilizes - making it more explicit than other formats.
CPHL requires specific key value pairs that can then be distributed across different platforms, such as JSON, XML, and YAML (see examples in repository).
CPHL is designed to be as flexible as possible, but does recommend the use of both the _definition and _links collections, although at minimum the _links collection is required.Based on HAL, CPHL is nestable meaning that you can utilize it for actions specific to the entire collection or singular result, or nest it within each item of the collection for that item's specific actions, or both.
_definition contains the collection of API definitions, as described by WADL, RAML, Swagger, or API Blueprint.The _definition collection breaks down into key value pairs where the name of the spec (camelCase, no spaces) represents the key, and the URL to the file containing the API defintion is the value.
"_definition" : {
"raml" : "http://api.domain.com/docs/api/raml",
"swagger" : "http://api.domain.com/docs/api/swagger"
}
Each individual link contains the following structure (optional constraints italic):
- title: the title of the action (eg: Edit User)
- description: a brief description of the action
- href: the URI for the client to achieve the action
- methods: an array of available methods to perform this specific action (eg edit: put, patch; view: get)
- formats: an array of formats that this action supports (ie JSON, XML, etc)
- {formatName}
- mimeType: the mime-type of the format (eg: application/json)
- schema: the URL to the schema for this format
- {formatName}
- docHref: the URL to online documentation for this action
- code: an array of available code libraries for this action
- {language}: the URL of the code library accessible to the client
"_links" : { "update" : { "title" : "Edit User", "description" : "edit the user", "href" : "/api/resource", "methods" : ["put", "patch"], "formats" : { "json" : { "mimeType" : "application/json", "schema" : "http://api.domain.com/docs/api/editSchema.json" }, "xml" : { "mimeType" : "text/xml", "schema" : "http://api.domain.com/docs/api/editSchema.xml" }, }, "docHref" : "http://api.domain.com/docs/edit", "code" : { "php" : "http://code.domain.com/phplib/edit.tgz", "java" : "http://code.domain.com/javalib/edit.tgz", "ruby" : "http://code.domain.com/rubylib/edit.tgz", } } }
<h4>application/cphl+xml</h4>
<_definition> http://api.domain.com/docs/api/raml http://api.domain.com/docs/api/swagger </_definition>
<_links>
<title>Edit User</title>
edit the user
/api/resource
put
patch
application/json
http://api.domain.com/docs/api/editSchema.json
text/xml
http://api.domain.com/docs/api/editSchema.xml
xml
http://api.domain.com/docs/edit
http://code.domain.com/phplib/edit.tgz
http://code.domain.com/javalib/edit.tgz
http://code.domain.com/rubylib/edit.tgz
</_links>
<h4>application/cphl+yaml</h4>
_definition: raml: http://api.domain.com/docs/api/raml swagger: http://api.domain.com/docs/api/swagger
_links: update: title: Edit User description: edit the user href: /api/resource methods: - put - patch formats: json: mimeType: application/json schema: http://api.domain.com/docs/api/editSchema.json xml: mimeType: text/json schema: http://api.domain.com/docs/api/editSchema.xml docHref: http://api.domain.com/docs/edit code: php: http://code.domain.com/phplib/edit.tgz java: http://code.domain.com/javalib/edit.tgz ruby: http://code.domain.com/rubylib/edit.tgz