Compendium Documentation

Application Fundamentals

Compendium Blogware is a hosted corporate blogging application. As with consumer blogging services, this application provides a means for creating and displaying content, but it has several features that differentiate itself from those services.

• The application is multiorganizational, meaning that it hosts all of its clients within a single instance of the application.
• The display of content, both blog posts and reader comments, is regulated by a moderator within the organization.
• Each blog post is associated with multiple blogs -- one which is associated with the content author, and several others which aggregate content according to topic. The association between post and blog is established by way of a textual analysis process called compending

Application Entities

There are several entities within the application.

Network

A network corresponds to an organization that using the blogging application. Networks have users and blogs. Networks may be assigned relationships with other networks for the purposes of delegated management.

User

A user corresponds to someone who has an ability to authenticate with the application to perform a task. The roles assigned to a user determine what the user may and may not do. Users may belong to only one network, but they may have roles that delegate the ability to perform some operations on other networks.

Blog

A blog corresponds to an aggregation of content. A blog which contains the content created by a single user is referred to as an individual or normal blog. A blog which contains content pertinent to a set of keywords is called a keyword or compended blog. Networks tend to have many more compended blogs than individual blogs. A network may also have an uberblog which contains all compendable posts on the network. Finally, every network has a hidden blog which may contain posts that serve as shared content, such as a "contact us" page.

Post

A post corresponds to an individual content unit created by a user. A post appears o a blog only after it has been approved for publication by user with moderation credentials. Posts may be sticky meaning that they will always be displayed first on the main page of a blog. Sticky posts are used typically as "about me items. They appear only on individual blogs.

Comment

A comment corresponds to an individual content unit created by a site visitor in response to a post. Abusive automated comment submission is protected by the use of a CAPTCHA.

Callback

A callback refers to an action that is to be taken in response to the occurrence of an event within the application. Typically, this action is a call to a web service external to the application. The callback will contain information specific to the type of event that occurred. Organizations may arrange to have callbacks set up for their network.

User Roles

User roles determine what permissions are held by a user. There are two base roles that are mutually exclusive. Every user on the application has one of these roles, but not both.

Default Permissions

The Default Permissions role is given to users who create blog content. They may save their content in draft form and submit it for approval to publish. They also have read access to any content they have created and any comments that were posted in reply to that content, regardless of approval status.

Network Administrator

The Network Administrator role is given to a special user that is created at the time a network is created. They are responsible for approving posts and comments submitted to blogs and posts on their network. Only one user may have this role, and it is non-transferrable. Users with this role may retrieve any submitted content on their network, regardless of publication status.

In addition to the base roles, a user may have additional roles granted.

Super Administrator

The Super Administrator role is given to a user who has the responsibility of administering networks within the application. They may create, modify, and delete networks. This role is assigned only to employees of Compendium Blogware on an as-needed basis.

Super Delegate

The Super Delegate role is given to network users whose network has been assigned to manage another network. This role is very similar to a Super Administrator, but it is constrained to a specific set of networks. Super Delegates may create networks, and when they do so, the new network will be assigned to the Super Delegate's network.

There are some quasi-roles that are bestowed upon users on a network that has been assigned to manage another network. This assignment is referred to as an Agency relationship. This allows user on the agency network to perform operations on behalf of their client networks.

Agency Admin

The Agency Admin role is automatically assigned to Network Administrators whose networks who have agency relationships. This role has the authority to assign users on his or her own network to one or more client networks.

Agency User

The Agency User role is automatically assigned to Default Permissions users whose networks have agency relationships. If an Agency User has been assigned to a client network, that user may log in as any user on that network without password (referred to as "proxy login"), and they may edit the blog template for that network.

Compendium Blogware Web Service API

Access to almost all of the application is mediated through a comprehensive web service API. The API is based largely upon the principles of RESTful architecture (see Alex Rodriguez's article at IBM's developerWorks for an introduction).

Manipulation of the entities described above are achieved through a set of resources that use the same name. Each resource may have one or more operations. Operations with read semantics are handled through the HTTP GET method. Operations with write semantics are handled largely through the HTTP POST method.

Access to a resource operation almost always requires some form of authentication. The roles for the user account being authenticated will determine what operations may be performed on the resource.

Authentication

Session Cookie Authentication

This form of authentication is used by the web interface to the application. A user initiates an HTTP POST operation with log-in name and password as parameters. The cookie set as part of the operation is associated with a session on the applicaiton server and may returned by the client as authentication for subsequent requests.

Remote Key Authentication

Networks may be granted the ability for their users to authenticate via a remote key. The key is a secret 128-bit string that can be submitted as part of API calls. The value of a user's remote key can be obtained and reset from the user's account settings page in the application.

Authentication via this route differs from session cookie authentication in the following ways:

• The client must use SSL to access the service by specifying https as the protocol in the URI.
• The client must include an HTTP Accept header (see RFC 2616, section 14.1) that indicates the desired API version and output representation. Version numbers will be noted in the API documentation.
• The client must supply the user's log-in name and remote key using HTTP Basic Authentication (see RFC 2617, Section 2 for more information).

Here is an example of an invocation of one of the Compendium Blogware service endpoints using the command line program cURL. To use this example for yourself, you will need to replace the value of the user parameter with your log-in name and key.

curl --insecure -H "Accept: application/vnd.compendium.blog;version=2,application/json" --user someuser:mgc3crqk45ufzkfb https://api.test.compendiumblog.com/app/date/format

This command makes the request without verifying the server's certificate. You will want to do this when developing against the test server because it uses a self-signed certificate.

Through the Accept header, it requests that the server use API version 2 with a response representation of JSON.

The creation of the Authentication header is handled through the --user parameter.

The response is a JSON encoded object with the current server time, expressed in ISO 8601 format.

{"Success":{"Date":"2009-06-12T14:23:46+00:00","FormatString":"c","FormattedDate":["2009-06-12T14:23:46+00:00"]}}

Conventions on HTTP Methods

In general, creation and update operations on resources are handled through the HTTP POST method.

Retrieval operations are handled through the HTTP GET method.

Operations on resources that have deletion effects are handled through the HTTP DELETE method. Because not all clients may support DELETE, the operation may also be submitted via POST.

Conventions on HTTP Status Codes

The API uses the following status codes in responses to requests:

200 OK

This is the default status code for a successful request.

201 Created

This code is used to indicate successful creation of an entity, such as a network or blog.

202 Accepted

This code is used to indicate that an asynchronous request was successfully received, such as a network recompend operation.

301 Moved Permanently

This code is used to redirect the client to a new permanent location for the request. If a client receives this as a result of an API request, the client's configuration should be updated to use the new resource location.

400 Bad Request

This code is used to inform the client that the input for the API was not valid and should be corrected before reattempting.

401 Unauthorized

This code is used to when the client makes an API request without any form of authentication.

403 Forbidden

This code is used when the client is authenticated as a user with insufficient permissions to perform the requested operation.

404 Not Found

This code is used when a request is made for a non-existent resource.

405 Method Not Allowed

This code is used when a resource does not support an HTTP method, like trying to update a user's attributes with an HTTP GET request.

500 Internal Server Error

This code is used when the application could not fulfill the request due to an unexpected condition. If you experience this problem repeatedly, you may want to contact engineering support for additional assistance.

API Versioning and Support Lifecycle

An endpoint's API version is incremented whenever a revision introduces a breaking change. Compendium has specific terms for endpoint versions:

Current

This is the latest public release of the service endpoint.

Supported

This is the previous public release of the service endpoint.

Deprecated

This is the next most previous public release of the service endpoint

As a new version becomes available, the deprecated version becomes unsupported. Developers should strive to maintain their code such that either the Current or Supported versions are always used. This will minimize the likelihood of service disruption when a new endpoint revision is released.

The current API version is 2.

Endpoint Hostnames and Environments

For development purposes, it is a best practice to perform operations using a test environment rather than a live environment. Compendium Blogware's engineering group maintains a test server that is refreshed on a regular basis. The host name for this server is api.test.compendiumblog.com. On days prior to release days, this server will host one or more release candidate cuts, which may result in limited availability. Please consult with the engineering group to find out the current release schedule and plan accordingly. The host name to be used for production activity is api.compendiumblog.com.

We strongly encourage development teams integrating with our application to ensure their code can be configured easily to run against either test or production environments.