This is the language used to describe the API in Captura Group's original formal proposal to develop GSA's social media registry (http://registry.usa.gov). The final requirements did change, but this high level description of the APIs was sufficient to ensure that APIs were part of the final product.

gistfile1.md

The social media outlet registration system will operate as a database that can receive and publish information through three desktop browser‐based interfaces that are powered by three corresponding APIs. The following describes core functionality, but final requirements will determine the precise functionality.

Interfaces

• A submission form where anyone with a verifiable government email address (.gov, .mil, .si.edu, etc) can enter information about official government social media outlets. Information gathered will include the name of the outlet (e.g. Facebook, Twitter, YouTube, etc), the user name corresponding to the official outlet, and other descriptive information that may include tags, zip codes, categories, sponsoring agencies and more.
• A verification form to allow anyone to authenticate an ostensibly official government social media outlet by entering the URL of that outlet into an input field or crafting a URL.
• A javascript‐based widget that will output lists of social media outlets based on a subset of meta data stored in the database.

APIs

• /post — receives the URL of a social media outlet along with a verifiable government email address. Could also receive a series of descriptive tags or categories. Will return a confirmation of information received and trigger an email with a confirmation link to the supplied email address.
• /verify — receives the URL of a social media outlet and return a value indicating if the URL has been entered into the database or not. May also return tags and categories associated with the URL.
• /get — receives sponsor agency, categories, tags, or outlet URLs and return lists of registered social media outlets matching those parameters.