/Developer Program

Procurement Language

Scenario A

Agency uses the below text as the scope of work for a task within a larger system creation/maintenance contract. This task could be included from the start or added as a modification to the contract.

The scope of work for this task includes the following activities:

• Design and develop the Application Program Interface (API) for [Name of System].
• Develop a widget that leverages the output of the API.
• Develop analytics capability to track API usage.
• Test API output.
• Create visual presentation of API output.
• Demo API functionality to stakeholders.
• Develop a section for the developers page within the [agency]’s website that promotes the API, along with supporting documentation for utilizing the API, including the following:
• Overview.
• Description and Lists of Query Fields.
• Sample queries with explanations.
• Examples of usage.

Scenario B

Agency includes the below text as part of its requirements for a contract, in order to ensure the API access to a specific system or dataset that the contractor is tasked to maintain.

The Contractor shall provide the technical capability that creates access to the data sources listed in task [##] via one or more APIs (Application Program Interface), web services solution (i.e., a software system designed to support interoperable machine-to-machine interaction over a network), or other relevant or useful Internet protocol (e.g., HTTP). Batch downloading of data source may [optional: ‘should’] be available but may not be the sole access; real-time, machine-readable access must be provided for all core data sources.

Where applicable and available, core platform infrastructure and capabilities may be provided through third-party services or providers. Such providers must meet specific contractual requirements for availability, reliability, and all Government requirements for security, terms of services, privacy, 508 compliance, etc.

Scenario C

Agency includes the below text as part of a general services IT contract, ensuring that the production and maintenance of APIs is part of the overall capabilities that the agency acquires.

The Contractor shall provide a complete information platform solution for purposes of supporting defined, directly-supported systems; increased use of information via open data and Web 2.0 strategies; and to support all activities in this SOW. The tasks to be performed include, but are not limited to, the following:

• Provide the content ownership and maintenance of databases and information sources core to program services and operations.
• Provide an Internet-based public platform for the use and sharing of content, information, and data, through the use of APIs (Application Program Interface) and open data formats.
• Provide, through maintenance, development, and operational support, the availability of the [program] website, and underlying systems and information technology that supports all program tasks and activities.
• Develop platform capabilities, web and Internet-based information sites, and services using the core sources and APIs.

Scenario D

Agency includes the below language in the Statement of Objectives for a services vendor procurement in order to require qualifying vendors to provide an API for the agency’s uses.

Application Programmer Interfaces (APIs)

• [System] shall allow additional information to be added/collected via an API or webform or both.
• Data collected in web forms can be easily and automatically submitted to the [system]
• [System] shall provide API access to [system] data so additional applications can be built and easily connected to the [system] database.

Scenario E

Agency already has a general services IT contract in place that provides developer resources capable of producing APIs. Further guidance to the contractor includes:

• The contractor shall provide online user documentation detailing the minimum requirements for correctly using the Web API. The documentation shall minimally contain examples showing the correct syntax of API requests and their corresponding responses.
• The contractor shall ensure that contact information for users seeking technical support is prominently displayed in the online Web API documentation.
• The contractor shall develop a strategy for maintaining Web API versions over the life-cycle of the task order. [optional] The contractor shall provide online, user-facing documentation that clearly distinguishes differences in usage between the current version of the Web API and its previous versions.
• The contractor shall provide quarterly reports that list the number of times the Web API has been used.

Scenario F

Agency includes the following text in its requirements listing for a general IT services contract, so as to have resources available for any agency API production or consumption needs.

The work will be planned and implemented in design and development of specific projects and enhancements, per planned releases and projects:

• Design, develop and maintain Java, JSP, Java Servlets, XML, Web Services against datasets in relational and flat databases.
• Design, develop and maintain Service-Oriented Architecture applications.
• Implement, test, and assist in the deployment of APIs.
• Document any APIs so that the information may be published in the developer resource’s section of the [agency] website and [agency] GitHub account.
• Perform knowledge transfer with [agency] personnel on how the API was implemented (via code review, etc.).
• Contribute to best practices developer guidelines for agency APIs.
• Test and integrate newly developed Java applications and web services.

Scenario G

Agency modifies an existing contract which has been used to build and maintain a specific system, using the below text to add a requirement that the contractor build an API for the system.

The goal of this addendum to incorporate an Optional Services task in Section [##] of the SOW, Software Engineering – Web Development to design, develop, test, document, and deploy an API (application programming interface) for the [Name of System]. Due to restrictions with the Government hosting facility, this API should be developed using the [XX] programming language. Additionally, the Government will provide an XML-formatted version of the content to be made accessible via the API as well as the current codebase used to create the [Name of System].

Specifically, this modification will require the following tasks to be performed:

• Assist in the definition of requirements for the API.
• Implement, test, and assist in the deployment of the API.
• Document the API so that the information may be published in the developer resource’s section of [agency].gov (http://www.[agency].gov/develolper).
• Perform knowledge transfer with [agency] personnel on how the API was implemented (via code review, etc…).
• Contribute to best practices developer guidelines for APIs.
• Identify opportunities to contribute code created for [agency] initiatives to open source projects, showing leadership in open government and technology.

Scenario H

Agency has an existing website with substantial amounts of data within it. They are now adding a deliverable to the existing contract behind the system to add a requirement for a read/write API.

1.0 INTRODUCTION:

1.1 The [NAME OF PROGRAM] Program manages [WEBSITE NAME, WEBSITE URL] and its associated [SYSTEM NAME, SYSTEM URL] in a collaborative effort to make [xxxxxx] opportunities and data available to the American and International public. These efforts meet the intentions of the Open Government and Data initiatives. This is an in-scope add-on to Contract # xxxxxxxxxx and Order # yyyyyyyyyyyy.

2.0 SCOPE:

This effort involves the development of a robust Application Programming Interface (API) that will give consumers easier and more manageable access to all [SYSTEM] data. The API shall be designed and developed to allow fully automated access to [SYSTEM] data by all interested consumers, as well as flexibility to filter and limit only subsets of the data as desired. The following elements and functionality shall be included in the development and delivery of the API:

2.1 Requirements/Discovery:

Customer interviews shall be conducted to learn more about their data needs. Use cases and mockups will be developed and presented to the [SYSTEM] COR for review and enhancement.

2.2 API Development:

• Registration – Requirement for data consumers to register for a free [SYSTEM] account in order to use the [SYSTEM] API.
• Authentication – Data consumers will be required to authenticate in order to interact with the API. This will provide the ability to generate audit trails and activity logs for use in reporting information such as total data feeds, unique feeds, and who is accessing the data.
• API Search and Filter Interfaces – Users shall be able to search for and retrieve [SYSTEM] data in a variety of useful ways described by the following. The ability to filter data by state, activity, and keyword are but a few of the options that will be available. The ability to export data in machine readable formats will be provided. Consumers using the API shall also have the ability to filter and export only data that has been updated within specified timeframes. Authorized data stewards using the API will be provided with interfaces to add, update, and delete their data.
• Logging and Reporting – All [SYSTEM] activity using the API will be logged to the database. Activity logs will be used to generate administrative reports of [SYSTEM] data consumer’s logins, searches, data downloads, and associated timeframes. This will aid in future analysis of [SYSTEM] data consumer’s needs.

2.3 API Testing:

A comprehensive test suite shall be developed in order to fully test all API functions.

2.4 Technical Documentation:

The API should be straightforward and easy to use, and written documentation shall be developed explaining the features and benefits. The documentation will be publically available on the [SYSTEM] website.

2.5 Goals (consistent with the Open Data Initiative):

• Increase the public’s ability to discover, view, and retrieve [SYSTEM] data
• Offer more machine readable formats for [SYSTEM] data consumption. XML is currently offered, but the API will also allow for JSON and CSV formats
• Increased interfaces for data contributors to insert and update [SYSTEM] data

2.6 Schedule:

The Contractor shall propose a schedule of development and delivery of all requested items above that includes associated milestones and final delivery date.

2.7 Timeframe:

The Government requests all deliverables be completed and delivered by MM-33-YYYY.

3.0 GOVERNMENT-FURNISHED EQUIPMENT (GFE) AND MATERIALS:

3.1 GFE: [SYSTEM] Database/Servers

3.2 Government Furnished Materials: [SYSTEM] data

4.0 DELIVERABLES: The table below provides a listing of deliverables, the media with the number of copies, and the recipients.

4.1 Deliverable #1 - Requirements use cases/mock ups from user interviews

4.2 Deliverable #2 – API Test Environment

4.3 Deliverable #3 – Fully developed and functional API: Containing the following features as described in Scope section 2.0: Registration, authentication, search/filter interfaces, logging and reporting

4.4 Deliverable #4 – API Technical Documentation

4.5 Deliverable Table: (milestone dates are negotiable – Contractor may propose an alternative schedule and milestones with approval by the Contracting Officer (CO) and Contracting Officer’s Representative [COR])

Assorted Modification Snippets

For use (or “ingesting”) API’s:

The Contractor must be able to deliver and maintain a solution that dynamically integrates both static and dynamic content into web and mobile site templates to provide a personalized user experience based on customer preferences, search results or user navigation choices. This combined content may come from multiple data sources (external API data feeds, widgets, internal database feeds, customer profile data, manual content entered via an internal content management system by staff or partners), as is done for registered users with stored preferences.

For creation of API’s:

Contractor shall expand [WEBSITE]’s ability to create machine readable data (for example, application programming interfaces (API’s) from other Federal agency web platforms as well as other web entities for the addition of content and data (including but not limited to programs, provisions and other various information).

To address code rights:

As part of this mutually agreed upon modification, in accordance with FAR 52.227-17, the contractor agrees that copyright ownership in all data/intellectual property, including but not limited to source code, text and images, first produced under the contract and incorporated in the deliverables on the updated Deliverables Schedule (date), is transferred to the agency name without restriction.

For any data/intellectual property not first produced under the contract and incorporated on the updated Deliverables Schedule (date), the contractor agrees that it has not, nor shall not, without prior written permission of the Contracting Officer, incorporate in such deliverables any data not first produced in the performance of this contract and that contain the copyright notice of 17 U.S.C. 401 or 402, unless the Contractor identifies such data and grants to the Government, or acquires on its behalf, a license of the same scope as set forth in paragraph (c)(1) of FAR 52.227-17.

General Guidance for any API procurement - From a presentation by Mulesoft

1. DESIGN AND DEVELOP APIS

HABIT #1: Apply an API-First design approach

1. RUN APIs

HABIT #2: Choose a solid API runtime

1. MANAGE AND SOCIALIZE APIS

HABIT #3: Create A Central Service Repository to allow people to easily find APIs

HABIT #4: Manage Services Through Versions, Policies and Contracts

• Security and throttling policies
• Carefully managing consumers of those APIs

HABIT #5: Promote and socialize your API

• Establishing a developer portal that is really easy for a developer to come in and use the API

HABIT #6: Monitor and Assess API usage

• Reviewing analytics metrics

HABIT #7: Refactor API to improve consumer experience & productivity