inadarei edited this page Apr 26, 2013 · 7 revisions

Some Technical Definitions

News Industry/NPR Lingo

  • Collection - a document type the primary purpose of which is to provide an ordered list of other documents (usually: stories). In PMP, collections are designed to be documents themselves: they have all the required attributes of a document, much like a story would. This is intentional and enables elegant recursive and abstract solutions for a number of problems.
  • association - a story is associated with a collection if it references that collection as a "parent".
  • ordered - a story is ordered in a collection if the collection contains the id of that story in its list of items. These are only the stories in the collection that are explicitly ordered when the collection is published; other stories may be associated with the collection but remain unordered.
  • publishing - creating or updating a document in the API
  • story - a document type that can have assets and appear in the items list of a collection.


  • API key - a secret key used for building a signature for a request.
  • endpoint - a URL which is supported by the API.
  • gateway - conceptually, the API that handles authentication and high-level validation, such as that we have a JSON object in PUT data.
  • guid - a Globally Unique IDentifier. Since we currently use UUID v4 standard to implement "guids", documentation uses "guid" and "uuid" interchangeably.
  • principal - an entity, in the security model, that can be a member of a security group. Common types of "principals" are: Organization and Individual.
  • namespacing - the system that provides the ability to publish non-core elements.
  • payload - contents of an API call's request or response body.
  • provider - conceptually, the API that handles getting and saving documents.
  • required elements - the list of JSON keys without which we cannot save a document.
  • signature - a string passed as the authentication mechanism, built using HMAC from the API key and an expire time.
  • token - synonym for signature.
  • storage - the permanent data store (such as a disk-backed database).

PMP Conceptual

  • core elements - the list of JSON keys which the code knows about, absent namespacing.

PMP Technical

  • module - a top level folder with code that doesn't depend directly on other code except through exports; some examples in our code are the documents, storages, and caches modules.