Documentation for expeDITA API for Content

The expeDITA framework is for developing applications that process simple DITA content. The original implementations fetched content from a local file system; this API provides a consistent manner of addressing and managing content in its underlying storage format (opaque to users, but may be a file system or database or other CMS).

Segments and syntax

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

'host','version','lang','verb','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: Only the 'get' (read) verb is presently supported for all segments in this API. Create, update, and delete verbs will be added, based on HTTP POST, PUT, and DELETE headers. For now, the function supports file browsing throughout sets of the sample DITA document repository (file based).

Segment definitions

host

The base hostname (this URL).

version

Currently v0, at an alpha stage of development.

lang

Placeholder for translation-differentiated versions of content. Example: en.

verb

Any of get | put | post | delete where:

get: retrieves the specified collection or resource
put: updates the specified resource (for collections, this is tantamount to "create new Group").
post: creates the specified type of resource (indeterminate for collections)
delete: deletes the named resource (indeterminate for collections)

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

Parameter entities

Properties of the requested resource are passed to the API engine by parameter entities (usually name=value expressions).

Normally the application that requests data using the API will be responsible for rendering the result according to theme or user requirements.

format: The default format returned by the API is xml. Add ?json to return JSON encoding.
doc: The singleton value ?doc returns browser-readable diagnostics and views.

Examples

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

Documentation for this API

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

Gets existing versions: e.g., 'v0'

Example: http://api.expedita.x10host.com/ (this page)

Returns: the documentation you are now reading.

Note: To see the API's internal documentation, add ?doc to the end of any of these following URL endpoints.

Service from the API effectively begins from this point.

Selector for API version

This endpoint hosts the logic for the corresponding version of API (anticipating that the interfaces may evolve over time).

Returns: list of available language versions for choice.

Example: http://api.expedita.x10host.com/v0/

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

Selector for language-differentiated data sets

This endpoint represents the selected language version of the assets. May not be meaningful for 'users' or 'events' when these are added.

Example: http://api.expedita.x10host.com/v0/en

Returns: none (this is a parameter, not a query).

HTTP "verb"

This endpoint represents the desired CRUD operation to be applied to the request.

Returns: a list of available groups.

(Note: a wrong value will return a reminder of the allowed values).

Example: http://api.expedita.x10host.com/v0/en/get

<groups>
	<group>BFH8</group>
	<group>CodexHelp</group>
	<group>IDM</group>
	<group>Light_Of_Day</group>
	<group>Lightweight_DITA</group>
	<group>Other</group>
	<group>ditaperday</group>
	<group>dxocrf</group>
	<group>taskbook</group>
</groups>

To be determined: Use the HTTP method names (get, put, post, delete) or common CRUD terms (read, create, update, delete)?

Note: the remaining segments are selectors for ever more specific content.

groupName--name of selected group

This endpoint represents the selected group of content.

Returns: a list of available resources in the group.

Example: http://api.expedita.x10host.com/v0/en/get/taskbook

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

queryType

This endpoint represents a typed or named set of content. The keywords of topic | map | filter create a collection of resources of that type. If a map is named instead of a type keyword, a collection is produced of the resources it names.

Returns: a list of resources by type (map, topic, ditaval) or by named set (map name) or by search hits.

Example by keyword: http://api.expedita.x10host.com/v0/en/get/taskbook/map

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

Example by named collection: http://api.expedita.x10host.com/v0/en/get/taskbook/main

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

resourceName

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.

Returns: the source of the named object.

Example: http://api.expedita.x10host.com/v0/en/get/taskbook/topic/taskbook-abstract

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

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

Example: http://api.expedita.x10host.com/v0/en/get/taskbook/main/taskbook-abstract

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

Parameter Query modifiers

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.

fmt=(xml | json): Format of the retrieved data. Default is 'xml'.
doc: A singleton value; if present, this query turns on the return of per-segment explanation and diagnostics (segment values, apparent controller, and values in the returned result). This query preempts any existing format value since it forces a mime type of 'text/html' in the browser.

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.
Light_Of_Day: Source content migrated from Don Day's original http://lightofday.wikifoundry.com/ wiki site.
Lightweight_DITA: Specification (in flux) and samples from the inception of the OASIS Lightweight DITA Subcommittee.
dita.xml.org: A migrated version of the OASIS dita.xml.org white paper on Conref Push. May add others.
ditaperday: expeDITA development test cases.
expeDITA_Docs: More expeDITA test cases and documentation of the platform proper.
taskbook: Sample content from the DITA Open Toolkit.