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).

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.

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
• 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