API for DITA Content: Reference

Introducing expeDITA API for Content

The expeDITA framework helps you develop DITA-awere applications that dynamically display simple DITA content. This API provides a consistent manner of addressing and managing content in its underlying storage format, whether in a file system on the server or via an integrated CCMS.

The client PHP component uses the cURL library to send requests to its server component using the HTTP verbs (PUT, GET, POST, and DELETE) along with a standard URL construction to request one or more resources. The client part maps these verbs to common application semantics of Create, Retrieve, Update, and Delete. The design conforms to the concept of Hypermedia As The Engine Of Application State (HATEOAS), the core principle of RESTful applications ().

This means that the URLs are strictly names for resources or collections of resources. Actions pertaining to the resources are conveyed through HTTP headers via the GET, PUT, POST, DELETE

Segments and syntax

A completely specified URL for this API consists of these segments:

'host','version','lang','dataType','groupName','queryType','resourceName'

Normally any less-than-full string of segments indicates a collection of the type of the closing segment in the string. In effect, a closing '/' and '/index' mean the same: both are a query for the preceding segment type.

Note on supported CRUD operators: All RESTful verbs are presently supported in the client PHP application. The server code interfaces with all verbs and fully decomposes all segments in this API. For now, function is limited to the GET (retrieve) function, which supports file browsing throughout sets of the sample, file-based, DITA document repository.

Segment definitions

host: The base hostname (this URL).
version: Currently v0, at a beta stage of development.
We follow recommendations at Apigee
lang: Any of en | es | he.... Placeholder for translation-differentiated versions of content..
dataType: Any of content | member | image | event.... This value points the addressing scheme to different types of data that may be managed by quite different underlying storage methods. Member data, for example, may be stored as SQL records, yet retrieved as XML records for publishing applications. Images may be retrieved by a key value rather than by a filename. Note that the present implementation only supports DITA as the canonical form of XML content at the moment. Not that other formats could not be included as well, but that use case will involve adding some property-passing methods as parameters.
groupName: The name of the group folder. A groupʼs name is an identifier that can represent ownership, projects, books, versions, and other such management of collections of content in your application.
queryType: The context for addressing a resource. For individually requested resources, this is a type keyword: topic | map | filter that represents a collection of resources of that type. Resources may be added to a named context called a map (think list or outline); when a mapʼs name is used in this segment, the resources named in it are the collection it represents. Examples include lists of bookmarks, saved search results, mindmap endpoints, outlines for books or white papers, and more.
resourceName: The unique identifier for the resource of the previously-indicated context. For content stored in a file system, the queryType/resourceName expeDITA name equates to a resourceName.extension filename where the extension represents the type of resource (.dita, .ditamap, .ditaval). The idenfier may also be a unique database primary key, expanded the same way for file-based operations on the content (upload, download, CRUD operations).

Using Segments to Query the Content

Each segment represents a query and retrieves a collection of corresponding hits. The final segment names an absolute resource within the collection.

API Hostname

This endpoint represents the documentation for the expeDITA API for Content.

Retrieves the API documentation (this document).

Example: http://api.xpdta.com/

Returns (null): the documentation you are now reading.

Note: To see contextual documentation for any endpoint, add ?doc after the last segment.

Service from the API effectively begins from this point.

Parameter: Select API version

Select the desired version of API (anticipating that the interfaces may evolve over time). This URL implicitly represents a request for as list of existing language sets, as the first actual information about what is available at the server.

Example: http://api.xpdta.com/v0/

Returns:

<langs>
<lang>en</lang>
</langs>

Select Language-differentiated data sets

This endpoint represents the selected language version of the assets. This category may not be meaningful for all data types (consider 'members' for example).

Example: http://api.xpdta.com/v0/en

Returns:

<datatypes>
<type>content</type>
</datatypes>

content

Select Available Data Type

This endpoint represents the selected data type (for example, 'content' or 'members').

Example: http://api.xpdta.com/v0/en/content

Returns:

<groups>
<group>BFH8</group>
<group>CodexHelp</group>
<group>StormCluster</group>
<group>taskbook</group>
</groups>

Note: The remaining segments comprise the expeDITA resource specifiers for collections of ever-more-specific content, ending in a single xpdname endpoint.

groupName--name of selected group

This endpoint represents the selected group of content.

Example: http://api.xpdta.com/v0/en/content/taskbook

Returns: a list of available resources in the group. The default type of resource is 'topic'; use the queryType segment to refine this result.

<list>
<name>topic/bookmap-readme</name>
<name>topic/closeprograms</name>
...
<name>topic/webtrouble</name>
<name>map/main</name>
</list>

queryType--qualifier for type of content in this group

This endpoint represents the qualifier (type or name) for a set of content. The keywords of topic | map | filter create collections of resources of each respective type. If a map is named instead of a type keyword, a collection is produced of the resources it names. [clarify: by type (map, topic, ditaval) or by named set (map name) or by search hits]

Example by keyword: http://api.xpdta.com/v0/en/content/taskbook/map

Returns: a list of resources of the named type.

<list>
<name>map/main</name>
</list>

Example by named collection: http://api.xpdta.com/v0/en/content/taskbook/main

Returns: a list of resources within the named map.

<list>
<name>topic/default</name>
<name>topic/taskbook-abstract</name>
...
<name>topic/webtrouble</name>
<name>topic/databasetrouble</name>
</list>

resourceName--unique identifier for a resource of this queryType

This endpoint represents the selected content endpoint, in either a standalone or contextualized "xpd name". If named after a keyword, the xpd name can be used to reference that resource individually. If named after a map name, the xpd represents that topicʼs context in that map. That is, both the resource and its containing map are implicitly represented in the xpd name, and can be used by an application to display the resource in context.

Example: http://api.xpdta.com/v0/en/content/taskbook/topic/taskbook-abstract

Returns: the source of the named object.

<concept id="concept-1">
<title>Abstract</title>
<conbody>
<p>
	A brief summary of all operational knowledge including the evolution of human culture.
</p>
</conbody>
</concept>

Resource in context

A topic referenced in a map can use that map's name as its "queryType". An application can use a resource's context to return a view of that resource in that mapped context (for example, where the context is a bookmark list or a table of contents). This context enables the use of reading sequence in paging navigation, for example. It also provides a map-level context from which dependent properties can be resolved.

Example: http://api.xpdta.com/v0/en/content/taskbook/main/taskbook-abstract

Returns: the source of the named object (identical to the singleton case).

<concept id="concept-1">
<title>Abstract</title>
<conbody>
<p>
A brief summary of all operational knowledge including the evolution of human culture.
</p>
</conbody>
</concept>

Format modifiers

The default format returned by the API is xml. The format can be changed by appending a format name as an "extension" to the resource name. For example, add .json to the resource name to return the resource data in JSON encoding.

Available formats include .xml and .json.

Note: Normally the application that requests data from the API will be responsible for rendering the result according to theme or user requirements. The .html format is being considered, but this form would have to be delivered as free from themed or conditional effects due to the headless nature of the request.

Parameter Queries

A parameter query is a name/value sequence concatenated to the URL by a single question mark character (?). Successive parameter query name/value sets are separated by an ampersand character (&). This is expected to be an extensible set.

doc: The singleton value ?doc returns browser-readable diagnostics and views.

HTTP Return Codes

Document the return codes generated by this API.

Disclaimers, road map and FAQ

This release of the expeDITA API for Content provides a test dataset made up of openly available DITA materials.

The present functionality is limited to XML as content; future content types may include images, user data, events, and so forth.

Notes on sources:

BFH8: The user manual for discontinued Bluetooth headphones (SoundLogic brand), scanned and migrated as DITA.
CodexHelp: The user manual for an early version of the Codex editor (DITA source offered by Adam Kozyniak).
IDM: A pretend user manual for a facetious product, to demonstrate formatting capabilities of the renderX PDF formatter (http://www.renderx.com/hammer.html), adapted to DITA.
StormCluster: A comprehensive DITA test case based on DITA 1.2 (but slightly modified for DITA 1.1 compatibility).
taskbook: Sample content from the DITA Open Toolkit.

Effective cURL get query

	$ch = curl_init();
	curl_setopt($ch,CURLOPT_USERAGENT, 'expeDITA Sample cURL Request');
	curl_setopt($ch, CURLOPT_TIMEOUT, 10);  
	curl_setopt($ch, CURLOPT_URL,$url);
	curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
	$response = curl_exec($ch);
	return $response;

Example URL passed to the get request:

http://api.xpdta.com/v0/en/content/taskbook/map/main.json

Appendix: Mapping HTTP verbs to CRUD services

For the following HTTP verbs, this design equates the practical intent to these CRUD service names:

GET: Retrieve the specified collection or resource.
PUT: Update the specified resource (for collections, this is tantamount to "create new Group").
POST: Creates the specified type of resource or collection.
DELETE: Delete the named resource or collection.