Tuesday, April 24, 2012

Draft API Manifesto

Here is the first cut on the API Overview Thesis.  The ideas are there, but the formatting/presentation is not and it promises to be a messy cutting room floor.

You can see the live version here, which will undoubtedly be changing.

Overview and Design Goals


SIGKAT provides a domain neutral API for creating, submitting, and verifying credentials. Our purpose is to increase the value of credentials by means that can be broadly divided into two categories. The first is reducing the impedance in credential economies. The second is broadening the currency of credentials.

This reduction in "heat loss" in credentialling activities translates directly into realizable value for existing participants in credential ecosystems as well as lowering the barriers to entry for new actors.
Impedance in credential economies is reduced via considerations of both technical and human factors. Technical issues include an easy to use json/REST API, a flexible object model, and, most importantly, much latitude in how SIGKAT credentialling features may be incorporated into other applications.

One major human factor is addressed by a design that allows credentialees and issuers to specify the level of privileged information and qualifying requirements that are necessary to satisfy the trust and reliability requirements of their credential types. Another important human factor design goal is absolutely minimizing the SIGKAT footprint in the end user's exercise of credentialling capabilities.

Finally, a human factor that should be clearly stated is that although we do provide an end use UI, SIGKAT ultimately is not a destination site. Our design goal and primary use case is end users engaging in occasional and incidental credentialling activities in the course of their primary engagement with an API client's activity.

To this purpose and to our engineering best practices, SIGKAT's public facing site is entirely built upon our API; we do not avail ourselves of any private or undocumented features. Other than account creation, anything that an end user can accomplish on our site, an API client may incorporate in their activity. And addressing issues surrounding account creation via the API is on our Roadmap.

Broadening the currency of credentials is also the subject of a several pronged strategy that, again, has both human and technical aspects. On the technical end, and possibly an economic one, we service both supply and demand side features. That is, providing API features to allow easy incorporation of both credential issuance and acceptance/verification at third party activities.

Our technical strategy for supporting broad currency includes releasing higher level API wrappers that can be dropped into popular application frameworks. Included in this are use cases where API clients extend and relay the SIGKAT API and become fully featured credential API providers themselves.

At the other end of the spectrum, where an API client is interested in simply a single point of functionality such as only verifying user credentials, we provide authentication schemes and resources that are lightweight and of minimum impact for clients and their users.

Finally, the human factor that is relevant to currency but even moreso to any success is that SIGKAT must be an honest and secure broker of credentialling information. In no way is our "product" users or their data. For more information, please see our Terms of Service and our Privacy Policy.

No comments:

Post a Comment