├── .about.yml ├── CONTRIBUTING.md ├── LICENSE.md ├── README.md ├── api-design ├── README.md └── overview.md ├── codeinventory.json └── working_group └── projects.md /.about.yml: -------------------------------------------------------------------------------- 1 | --- 2 | # .about.yml project metadata 3 | # 4 | # Short name that acts as the project identifier (required) 5 | name: api-standards 6 | 7 | # Full proper name of the project (required) 8 | full_name: GSA API Standards 9 | 10 | # The type of content in the repo 11 | # values: app, docs, policy 12 | type: policy 13 | 14 | # Describes whether a project team, working group/guild, etc. owns the repo (required) 15 | # values: guild, working-group, project 16 | owner_type: working-group 17 | 18 | # Maturity stage of the project (required) 19 | # values: discovery, alpha, beta, live, sunset, transfer, end 20 | stage: discovery 21 | 22 | # Description of the project 23 | description: GSA's recommended API best practices and standards 24 | 25 | # Tags that describe the project or aspects of the project 26 | tags: [standards, best-practices, apis, guides] 27 | 28 | # Should be 'true' if the project has a continuous build (required) 29 | # values: true, false 30 | testable: false 31 | 32 | # Team members contributing to the project (required) 33 | # Items: 34 | # - github: GitHub user name 35 | # id: Internal team identifier/user name 36 | # role: Team member's role; leads should be designated as 'lead' 37 | 38 | # NOTE from arowla: In choosing team members, I went with contributors 39 | # who are still at 18F who have made at least 2 commits. Many other people 40 | # have made valuable contributions to this project. 41 | # 42 | team: 43 | - github: rdgsa 44 | id: ryan 45 | role: lead 46 | - github: gbinal 47 | id: gray 48 | role: contributor 49 | 50 | # Licenses that apply to the project and/or its components (required) 51 | licenses: 52 | api-standards: 53 | name: CC0 54 | url: https://github.com/GSA/api-standards/blob/master/LICENSE.md 55 | -------------------------------------------------------------------------------- /CONTRIBUTING.md: -------------------------------------------------------------------------------- 1 | ## Contributing to GSA API Standards 2 | 3 | These API Standards are intended to begin the discussion within GSA for API best practices. We invite all GSA stakeholders to contribute to these standards and keep the conversation going. 4 | 5 | ## Ways to contribute: 6 | 7 | ### If have a github account: 8 | Review the readme.md, and [add issues](https://github.com/GSA/api-standards/issues) or pull requests directly in this github repo. 9 | 10 | ### If you don't have a github account: 11 | Review the readme.md, and send comments to ryan.day@gsa.gov. 12 | 13 | 14 | 15 | We encourage you to read this project's CONTRIBUTING policy (you are here), its [LICENSE](LICENSE.md), and its [README](README.md). 16 | 17 | If you have any questions or want to read more, contact the GSA Digital Services group. 18 | 19 | ## Public domain 20 | 21 | This project is in the public domain within the United States, and 22 | copyright and related rights in the work worldwide are waived through 23 | the [CC0 1.0 Universal public domain dedication](https://creativecommons.org/publicdomain/zero/1.0/). 24 | 25 | All contributions to this project will be released under the CC0 26 | dedication. By submitting a pull request, you are agreeing to comply 27 | with this waiver of copyright interest. 28 | -------------------------------------------------------------------------------- /LICENSE.md: -------------------------------------------------------------------------------- 1 | As a work of the United States Government, this project is in the 2 | public domain within the United States. 3 | 4 | Additionally, we waive copyright and related rights in the work 5 | worldwide through the CC0 1.0 Universal public domain dedication. 6 | 7 | ## CC0 1.0 Universal Summary 8 | 9 | This is a human-readable summary of the [Legal Code (read the full text)](https://creativecommons.org/publicdomain/zero/1.0/legalcode). 10 | 11 | ### No Copyright 12 | 13 | The person who associated a work with this deed has dedicated the work to 14 | the public domain by waiving all of his or her rights to the work worldwide 15 | under copyright law, including all related and neighboring rights, to the 16 | extent allowed by law. 17 | 18 | You can copy, modify, distribute and perform the work, even for commercial 19 | purposes, all without asking permission. 20 | 21 | ### Other Information 22 | 23 | In no way are the patent or trademark rights of any person affected by CC0, 24 | nor are the rights that other persons may have in the work or in how the 25 | work is used, such as publicity or privacy rights. 26 | 27 | Unless expressly stated otherwise, the person who associated a work with 28 | this deed makes no warranties about the work, and disclaims liability for 29 | all uses of the work, to the fullest extent permitted by applicable law. 30 | When using or citing the work, you should not imply endorsement by the 31 | author or the affirmer. 32 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # GSA API Standards 2 | 3 | This document captures **GSA's recommended best practices, conventions, and standards for Application Programming Interfaces (APIs)**. Projects should start by addressing [API Security](#api-security), followed by implementing the [Mandatory Items](#mandatory-items) and [Mandatory For New Public APIs](#mandatory-for-new-public-apis). After addressing those, review [Other Considerations](#other-considerations) for additional advice. 4 | 5 | ## Contents 6 | - [About These Standards](#about-these-standards) 7 | - [API Security](#api-security) 8 | - [Mandatory Items for Public APIs](#mandatory-items-for-public-apis) 9 | - [Recommended Items for Public APIs](#recommended-items-for-public-apis) 10 | - [Mandatory Items for Limited Partner APIs](#mandatory-items-for-limited-partner-apis) 11 | - [Recommended Items for Limited Partner APIs](#recommended-items-for-limited-partner-apis) 12 | - [Other Considerations](#other-considerations) 13 | - [API Testing](#api-testing) 14 | - [SOAP Web Services](#soap-web-services) 15 | - [Future Topics](#future-topics) 16 | 17 | 18 | ## About These Standards 19 | 20 | These standards are forked from the [18F API Standards](https://github.com/18F/api-standards). They are also influenced by several other sources, including the [White House API Standards](https://github.com/WhiteHouse/api-standards) and best practices from the private sector. 21 | 22 | ### The standards are a roadmap not a roadblock 23 | 24 | These standards are intended to streamline the process for GSA organizations to publish new APIs by providing practical and pragmatic advice. We believe these standards will benefit GSA API development and provide consistency. 25 | 26 | 27 | ### They primarily focus on RESTful APIs 28 | Most of the content in these standards relates to "RESTful" APIs. However, many of the standards are equally appropriate for other types of web service. 29 | 30 | A few specific recommendations are provided for [SOAP web services](#soap-web-services), and we encourage the GSA community to share more recommendations. 31 | 32 | ### They don't look under the covers 33 | Because APIs may be developed with multiple technologies, these standards avoid details internal to the development of the application or unique to a development platform. They generally focus on the "externals" that will be exposed to users. 34 | 35 | ### API Category Definitions 36 | 37 | For the purposes of these standards, we use the following definitions: 38 | * **Non Public APIs** - Available only to GSA applications and users. 39 | * **Public APIs** - Available to non-GSA applications and users. Examples include the general public, other agencies, or private companies. 40 | * **Limited Partner APIs** - Available to two or fewer non-GSA applications or users. Examples include other agencies or private companies. 41 | 42 | ## API Security 43 | API Security is governed by the GSA IT Security Procedural Guide: API Security CIO-IT Security-19-93. Reference that guide for security related topics such as HTTPS encryption, authentication, and authorization. 44 | 45 | ## Mandatory Items for Public APIs ## 46 | 47 | These are mandatory for GSA public APIs, with exceptions where noted. 48 | 49 | ### 1. Add Your API To The GSA API Directory 50 | (Public APIs) A directory of GSA public APIs is available at [open.gsa.gov/api](https://open.gsa.gov/api/). Add your API to this directory by posting an issue or pull request in the [GitHub repository](https://github.com/GSA/open-gsa-redesign). 51 | 52 | Part of this process is to first complete the neccessary steps to add your GitHub Account to the GSA Organization and then send an email to the CTO team to have your account added to the open-gsa-redesign User Group. The steps are documented on the [Adding API Documentation](https://github.com/GSA/open-gsa-redesign/blob/master/APIDOCS.md) GitHub page. 53 | 54 | ### 2. Use The api.data.gov Service 55 | 56 | (Public APIs) The [api.data.gov service](https://api.data.gov/about/) is an API management service for federal agencies. GSA APIs should use the `api.gsa.gov` base domain with this service. By having the `api.gsa.gov` base URL as a proxy to developers, this also makes it easier to update and maintain the API in the future since you can update the underlying system and URLs without exposing it to the public. In some cases, other specific base domains can be established with this service for GSA APIs. 57 | 58 | #### Implementing With Your API 59 | Initially, this service can be added as a new version of the URL, and then existing users can be transitioned to the new URL. For help setting this up, contact the api.data.gov team at . 60 | 61 | #### Additional Benefits 62 | The api.gsa.gov service also provides: 63 | * API key management 64 | * rate limiting (throttling) 65 | * gathering usage statistics (analytics) 66 | 67 | Keys managed by api.data.gov can be re-used with other APIs hosted by this service, which reduces complexity for users. This service also allows the use of a DEMO_KEY for unauthenticated access, without keys, which reduces the "Time To First Hello World" for developers using your API. 68 | 69 | _Exceptions: Not required for SOAP APIs. However, it may still provide value to your SOAP API._ 70 | 71 | ### 3. Provide Support For Versioning 72 | All APIs must support versioning. The recommended method of versioning REST APIs is to include a major version number in the URL path. For example "/v1/". An example of this method can be found at: https://gsa.github.io/sam_api/sam/versioning.html. 73 | 74 | #### Major and Minor Versions 75 | Major versions (e.g. v1, v2) should be reserved for breaking changes and major releases. Minor versions (eg. 1.1, 2.3) are not required, but can provide additional information about the API. If used, they should not be in the URL, but should be in the HTTP Headers. 76 | 77 | #### Breaking Changes (backwards-incompatible) 78 | Any changes made to a specific version of your API should not break your contract with existing users. If you need to make a change that will break that contract, create a new major version. 79 | 80 | Examples of Breaking Changes for REST APIs: 81 | - Removing an HTTP method 82 | - Removing or renaming a field in the request or response message 83 | - Removing or renaming a query parameter 84 | - Changing the URL or URL format 85 | 86 | Examples of Breaking Changes for SOAP web services: 87 | - Removing an operation 88 | - Renaming an operation 89 | - Changing the parameters (in data type or order) of an operation 90 | - Changing the structure of a complex data type. 91 | 92 | #### Non-Breaking Changes (backwards-compatible) 93 | It is not necessary to increment the major API version for non-breaking changes. Non-breaking changes can be reflected in a minor version, if used. 94 | 95 | Examples of Non-Breaking Changes for REST APIs: 96 | - Adding an HTTP method 97 | - Adding a field to a request message 98 | - Adding a field to a response message 99 | - Adding a value to an enum 100 | - Adding a query parameter 101 | 102 | Examples of Non-Breaking Changes for SOAP web services: 103 | - Adding a new WSDL operation to an existing WSDL document. 104 | - Adding a new XML schema type within a WSDL document that are not contained within previously existing types 105 | 106 | 107 | #### Support for Previous Versions 108 | Leave at least one previous major version intact. And communicate to existing users to understand when previous versions will be decommissioned. 109 | 110 | #### Prototype or Alpha Versions 111 | Use "/v0/" to represent an API that is in prototype or alpha phase and is likely to change frequently without warning. 112 | 113 | ### 4. Provide Public Documentation 114 | The developer's entry point to your API will likely be the documentation that you provide. 115 | 116 | Your API documentation should provide: 117 | * An overview of the contents of the API and the data sources. 118 | * Public APIs should provide production URLs for accessing the API. (Non-public APIs would exclude this.) 119 | * Required parameters and defaults. 120 | * A description of the data that is returned. 121 | * A description of the error codes that are returned, and their meaning. 122 | 123 | Additional nice-to-haves include: 124 | * Explanation of key management and a sample key. 125 | * Description of update frequency. 126 | * Interactive documentation to demonstrate sample calls. 127 | * Sample client code for consuming the API in common languages. 128 | 129 | ### 5. Provide A Feedback Mechanism That Is Clear and Monitored 130 | 131 | Have an obvious mechanism for clients to report issues and ask questions about the API. It is critical to respond to issues posted or queries submitted by developers. This demonstrates that the API can be counted on for production usage. If an immediate fix (or even a developer to investigate) is not readily available, respond anyway. Developers will be glad to know when you'll be able to take a look. 132 | 133 | When using GitHub for an API's code or documentation, use the associated issue tracker. In addition, publish an email address for direct, non-public inquiries. 134 | 135 | If you don't have a support channel specific to your API, you can use the issue tracker at [GSA-APIs](https://github.com/GSA/GSA-APIs/issues). Be sure your support team subscribes to issues there. 136 | 137 | ### 6. Provide An OpenAPI Specification File 138 | For REST APIs, The API documentation should provide a clear link to the [API's OpenAPI Specification file](https://github.com/OAI/OpenAPI-Specification). This specification was formerly known as the Swagger specification. This specification file can be used by development or testing tools accessing your API. 139 | 140 | Using Version 2.0 or later of the specification is recommended. Information about versions can be found here: [OpenAPI Specification Revision History](https://swagger.io/specification/#revisionHistory). 141 | 142 | _Exceptions: Not required for SOAP APIs._ 143 | 144 | ### 7. Follow The Standard API Endpoint Design 145 | For REST APIs, An "endpoint" is a combination of two things: 146 | 147 | * The verb (e.g. `GET` , `POST`, `PUT`, `PATCH`, `DELETE`) 148 | * The URL path (e.g. `/articles`) 149 | 150 | The URL path should follow this pattern for a collection of items: 151 | `(base domain)/{business_function}/{application_name}/{major version}/{plural_noun}` 152 | 153 | An example would be: 154 | `https://api.gsa.gov/financial_management/sample_app/v1/vendors` 155 | 156 | The URL path for an individual item in this collection would default to: 157 | `(base domain)/{business_function}/{application_name}/{major version}/{plural_noun}/{identifier}` 158 | 159 | An example would be: 160 | `https://api.gsa.gov/financial_management/sample_app/v1/vendors/123` 161 | 162 | _Exceptions: Not required for SOAP APIs. Not required for APIs that were in progress or production prior to December 2018._ 163 | 164 | 165 | ## Recommended Items for Public APIs 166 | 167 | ### 1. Provide a Testing UI 168 | 169 | When you have an OpenAPI specification file (mandatory for public APIs), there are tools that can use this specification file to automatically generate a page where your users can try out your API without too much effort. [Swagger UI is one such tool; here is an example](https://petstore.swagger.io/). 170 | 171 | We strongly recommend implementing this item, as it provides a significant enhancement to developer experience and helps ensure proper use of your API. Swagger UI can be implemented on any website, even a static site, with the inclusion of a few JavaScript and CSS files. 172 | 173 | [See the Swagger UI project for installation and configuration instructions](https://github.com/swagger-api/swagger-ui). 174 | 175 | After downloading Swagger UI, you generally will want a page that loads the Swagger UI and your OpenAPI specification file: 176 | 177 | ```html 178 | 179 | 180 | 181 | 182 |
183 | 184 | 185 | 200 | ``` 201 | 202 | Depending on your site, the above is roughly all you need to generate the API testing tool. 203 | 204 | 205 | ## Mandatory Items for Limited Partner APIs 206 | 207 | 208 | ### 1. Provide Public or Protected Documentation 209 | 210 | If details of API need to be secured from public viewing, the API documentation can be on a web page that is only accessible to authorized users of the API. This protected documentation may be mentioned on a separate public page, or directly linked from the API Directory. 211 | 212 | Your API documentation should provide: 213 | * An overview of the contents of the API and the data sources. 214 | * Required parameters and defaults. 215 | * A description of the data that is returned. 216 | * A description of the error codes that are returned, and their meaning. 217 | 218 | Additional nice-to-haves include: 219 | * Explanation of key management and a sample key. 220 | * Description of update frequency. 221 | * Interactive documentation to demonstrate sample calls. 222 | * Sample client code for consuming the API in common languages. 223 | 224 | ### 2. Provide A Feedback Mechanism That Is Clear and Monitored 225 | 226 | On the public or protected documentation page, include a method for users to report issues and ask questions about the API. It is critical to respond to issues posted or queries submitted by developers. This demonstrates that the API can be counted on for production usage. If an immediate fix (or even a developer to investigate) is not readily available, respond anyway. Developers will be glad to know when you'll be able to take a look. 227 | 228 | ## Recommended Items for Limited Partner APIs 229 | 230 | The following items will be beneficial to the users of your APIs. (Full details of these items are linked to the previous section of this document.) 231 | 232 | [Add Your API To The GSA API Directory](#1-add-your-api-to-the-gsa-api-directory) 233 | [Use The api.data.gov Service](#2-use-the-apidatagov-service) 234 | [Provide Support For Versioning](#3-provide-support-for-versioning) 235 | [Provide An OpenAPI Specification File](#6-provide-an-openapi-specification-file) 236 | [Follow the Standard API Endpoint Design](#7-follow-the-standard-api-endpoint-design) 237 | 238 | 239 | 240 | 241 | 242 | 243 | 244 | ## Other Considerations 245 | 246 | ### Design for common use cases 247 | 248 | For APIs that syndicate data, consider several common client use cases: 249 | 250 | * **Bulk data.** Clients often wish to establish their own copy of the API's dataset in its entirety. For example, someone might like to build their own search engine on top of the dataset, using different parameters and technology than the "official" API allows. If the API can't easily act as a bulk data provider, provide a separate mechanism for acquiring the backing dataset in bulk, such as posting the full dataset on [data.gov](https://www.data.gov/). 251 | * **Staying up to date.** Especially for large datasets, clients may want to keep their dataset up to date without downloading the data set after every change. If this is a use case for the API, prioritize it in the design. 252 | * **Driving expensive actions.** What would happen if a client wanted to automatically send text messages to thousands of people or light up the side of a skyscraper every time a new record appears? Consider whether the API's records will always be in a reliable unchanging order, and whether they tend to appear in clumps or in a steady stream. Generally speaking, consider the "entropy" an API client would experience. 253 | 254 | ### Using one's own API 255 | 256 | The best way to understand and address the weaknesses in an API's design and implementation is to use it in a production system. 257 | 258 | Whenever feasible, design an API in parallel with an accompanying integration of that API. 259 | 260 | A few methods to accomplish this include: 261 | * Identifying an internal GSA organization to use your API while also publishing it publicly. 262 | * Creating a web page with a search feature that uses the API. 263 | * Modifying existing web pages or web applications to use the API instead of direct access to the database. 264 | 265 | ### Developers Are Your End Users 266 | Consider developers who will be using your APIs. Their path to using your API will include discovery and initial investigation, sample API calls, development and testing, deployment and production usage. Consider each of these functions in your documentation, support, and change notification process. Consider performing formal API Usability Testing to understand the developer experience in using your API. More information about this type of testing is available here: [API Usability Testing](https://pages.18f.gov/API-Usability-Testing/). 267 | 268 | ### Notifications of updates 269 | 270 | Have a simple mechanism for clients to follow changes to the API. 271 | 272 | Common ways to do this include a mailing list or a persistent issue in the GitHub repository that users can subscribe to. For example: [Notification Thread: Updates to GSA APIs](https://github.com/GSA/GSA-APIs/issues/46) 273 | 274 | ### Decommission unsupported APIs 275 | 276 | If an API can no longer be supported, consider decommissioning the API and removing the documentation. If the API will remain available for historical purposes without support, update the documentation to reflect this. 277 | 278 | ### Notify current users and update documentation before breaking changes or decommissioning 279 | 280 | If an API is going to be decommissioned, retired, or [changed in such a way that current users will be impacted](https://github.com/GSA/api-standards#breaking-changes-backwards-incompatible), it is critical that those users be notified in advance so that they can prepare for the change instead of experiencing an unexpected interruption. The most common situations where this happens is if an API is going to be decommissioned or if an update to the API will change how the API functions (note that this is where [Versioning](https://github.com/GSA/api-standards#3-provide-support-for-versioning) is important). If these users aren't notified, their application that consumes the API [may break](https://github.com/GSA/api-standards#breaking-changes-backwards-incompatible) and they may suffer significant consequences from their application's resulting downtime. Furthermore, experiencing this may seriously degrade the trust that the developer has in GSA's API programs and may cause them to avoid our services going forward if they feel that they cannot rely on them. 281 | 282 | In addition to updating the API documentation in advance with a highly visible notice, it is important to use [API analytics](https://github.com/GSA/api-standards#2-use-the-apidatagov-service) to see which API keys have consumed the service in recent months. You can then use the email addresses associated with each key to send (preferably more than one) notification of the upcoming change. Note that posting a notice on the API documentation is not sufficient by itself, as many current users will not necessarily revisit the documentatation. Proactive notification of recent users is essential. 283 | 284 | ### Use JSON 285 | 286 | [JSON](https://en.wikipedia.org/wiki/JSON) is an excellent, widely supported transport format, suitable for many web APIs. 287 | 288 | Supporting JSON and only JSON is a practical default for APIs, and generally reduces complexity for both the API provider and consumer. 289 | 290 | General JSON guidelines: 291 | 292 | * Responses should be **a JSON object** (not an array). Using an array to return results limits the ability to include metadata about results, and limits the API's ability to add additional top-level keys in the future. If multiple results are returned, they can be included as an Array in the JSON object. 293 | * **Don't use unpredictable keys**. Parsing a JSON response where keys are unpredictable (e.g. derived from data) is difficult, and adds friction for clients. 294 | * **Use consistent case for keys**. Whether you use `under_score` or `CamelCase` for your API keys, make sure you are consistent. 295 | 296 | ### Use a consistent date format 297 | 298 | And specifically, [use ISO 8601](https://xkcd.com/1179/), in UTC. 299 | 300 | For just dates, that looks like `2013-02-27`. For full times, that's of the form `2013-02-27T10:00:00Z`. 301 | 302 | This date format is used all over the web, and puts each field in consistent order -- from least granular to most granular. 303 | 304 | ### HTTP Response Codes 305 | 306 | The following are recommended HTTP Response Codes that API should return. They are based on the [OWASP REST Security Cheat Sheet](https://www.owasp.org/index.php/REST_Security_Cheat_Sheet) from December 2018. 307 | 308 | | Return Code | Message | Description | 309 | | --- | ----- | --------------------- | 310 | | 200 | OK | Response to a successful REST API action. The HTTP method can be GET, POST, PUT, PATCH or DELETE. | 311 | | 201 | Created | The request has been fulfilled and the resource created. A URL for the created resource is returned in the Location header. | 312 | | 202 | Accepted | The request has been accepted for processing, but processing is not yet complete | 313 | | 400 | Bad Request | The request is malformed, such as a message body format error, missing headers, etc. | 314 | | 401 | Unauthorized | Wrong or no authentication ID/ password provided. | 315 | | 403 | Forbidden | Used when the authentication succeeded but the authenticated user does not have permission to the requested resource. | 316 | | 404 | Not Found | When a non-existent resource is requested. | 317 | | 406 | Unacceptable | The client presented a content type in the Accept header which is not supported by the server API. | 318 | | 405 | Method Not Allowed | The error for an unexpected HTTP method. For example, the REST API is expecting HTTP GET, but HTTP PUT is used. | 319 | | 413 | Payload Too Large | Used to signal that the request size exceeded the given limit (e.g. regarding file uploads and to ensure that the requests have reasonable sizes). | 320 | | 415 | Unsupported Media Type | The requested content type is not supported by the REST service. This is especially effective when you are working primary with JSON or XML media types. | 321 | | 429 | Too Many Requests | The error is used when there may be a DOS attack detected or the request is rejected due to rate limiting. | 322 | | 500 | Internal Server Error | An unexpected condition prevented the server from fulfilling the request. Be aware that the response should not reveal internal information that helps an attacker, e.g. detailed error messages or stack traces. | 323 | | 501 | Not Implemented | The REST service does not implement the requested operation yet | 324 | | 502 | Service Unavailable | The REST service is temporarily unable to process the request. Used to inform the client it should retry at a later time. | 325 | 326 | Note: GSA APIs [should be using the api.data.gov service](#3-use-the-apidatagov-service) as a proxy between the client and the API. That service will return additional HTTP codes, prior to the request reaching the base API. Here is a list of those code: [https://api.data.gov/docs/errors/](https://api.data.gov/docs/errors/) 327 | 328 | ### Pagination 329 | 330 | If pagination is required to navigate datasets, use the method that makes the most sense for the API's data. 331 | 332 | Common patterns: 333 | 334 | * `page` and `per_page`. Intuitive for many use cases. Links to "page 2" may not always contain the same data. 335 | * `offset` and `limit`. This standard comes from the SQL database world, and is a good option when you need stable permalinks to result sets. 336 | * `since` and `limit`. Get everything "since" some ID or timestamp. Useful when it's a priority to let clients efficiently stay "in sync" with data. Generally requires result set order to be very stable. 337 | 338 | ### Metadata 339 | 340 | Include enough metadata so that clients can calculate how much data there is, and how and whether to fetch the next set of results. 341 | 342 | Example of how that might be implemented: 343 | 344 | ```json 345 | { 346 | "results": [ ... actual results ... ], 347 | "pagination": { 348 | "count": 2340, 349 | "page": 4, 350 | "per_page": 20 351 | } 352 | } 353 | ``` 354 | 355 | ### Use UTF-8 356 | 357 | Just [use UTF-8](http://utf8everywhere.org). 358 | 359 | Handle accented characters or "smart quotes" in API output, even if they're not expected. 360 | 361 | An API should tell clients to expect UTF-8 by including a charset notation in the `Content-Type` header for responses. 362 | 363 | An API that returns JSON should use: 364 | 365 | ``` 366 | Content-Type: application/json; charset=utf-8 367 | ``` 368 | 369 | ### Enable CORS 370 | 371 | For clients to be able to use an API from inside web browsers, the API must [enable Cross-Original Resource Sharing (CORS)](http://enable-cors.org). 372 | 373 | For the simplest and most common use case, where the entire API should be accessible from inside the browser, enabling CORS is as simple as including this HTTP header in all responses: 374 | 375 | ``` 376 | Access-Control-Allow-Origin: * 377 | ``` 378 | 379 | It's supported by [every modern browser](http://enable-cors.org/client.html), and will Just Work in many JavaScript clients. 380 | 381 | For additional guidance on CORS, see the GSA IT Security Procedural Guide: API Security CIO-IT Security-19-93. 382 | 383 | ## API Testing 384 | 385 | At its most basic level, API testing is intended to reveal bugs: inconsistencies or deviations from the expected behavior. Continuous testing is also very important to make sure it continues to work when the public has access to it. The risk of putting a bad, and potentially insecure, product on the market is greater than the cost to test it. 386 | 387 | **Types of API Testing** 388 | - **Functionality testing** — the API works and does exactly what it’s supposed to do. 389 | - **Reliability testing** — the API can be consistently connected to and lead to consistent results. 390 | - **Load testing** — the API can handle a large amount of calls. 391 | - **Creativity testing** — the API can handle being used in different ways. 392 | - **Security testing** — the API has defined security requirements including authentication, permissions and access controls. 393 | - **Proficiency testing** — the API increases what developers are able to do. 394 | - **API documentation testing** — also called discovery testing, the API documentation easily guides the user. 395 | - **Negative Testing** — checking for every kind of wrong input the user can possibly supply. 396 | 397 | 398 | ## SOAP Web Services 399 | * Provide a WSDL. 400 | 401 | Most platforms will provide this by default out of the box. Leave it active unless you have a strong reason not to. A useful convention is that the WSDL will be available at: {URL Path)?wsdl 402 | 403 | * Provide documentation for SOAP web services. 404 | 405 | Users of SOAP web services need documentation, just like REST users. 406 | 407 | * See examples of versioning of SOAP web services above. 408 | 409 | ## Future Topics 410 | Several additional API related topics continue to emerge and will be considered for future updates to these standards. 411 | 412 | That list includes: 413 | * Microservices 414 | * Hypermedia and HATEOAS 415 | * Responsive APIs 416 | * GraphQL 417 | 418 | ### What are we missing? 419 | If you see a future topic we need to consider, take a look at our [contributing page](https://github.com/GSA/api-standards/blob/master/CONTRIBUTING.md) for instructions to share that info. 420 | -------------------------------------------------------------------------------- /api-design/README.md: -------------------------------------------------------------------------------- 1 | 2 | ## Endpoint Design - Tracking 3 | 4 | 5 | | API | Current Endpoint | Proposed Endpoint | 6 | |---|---|---| 7 | | Acquisition Gateway API | https://hallways.cap.gsa.gov/api/v1.0 | https://api.gsa.gov/acquisition/cap/v1/ | 8 | | [analytics.usa.gov](https://analytics.usa.gov/developer) | https://api.gsa.gov/analytics/dap/ | https://api.gsa.gov/analytics/dap/v1/ | 9 | | [api.data.gov Admin API](http://api.data.gov/developer/) | https://api.data.gov/operations/api-api-umbrella/v1/ | https://api.gsa.gov/operations/api-api-umbrella/v1/ | 10 | | [api.data.gov Metrics API](http://api.data.gov/developer/) | https://api.data.gov/operations/api-api-umbrella/v1/ | https://api.gsa.gov/operations/api-api-umbrella/v1/ | 11 | | [Auctions API](http://gsa.github.io/auctions_api/) | https://api.data.gov/gsa/auctions | https://api.gsa.gov/assets/gsaauctions/v2/auctions | 12 | | Calc | https://calc.gsa.gov/api/ | https://api.gsa.gov/acquisition/calc/v1/ | 13 | | [Data.gov CKAN API](http://www.data.gov/developers/apis) | http://catalog.data.gov/api/3/ | http://api.gsa.gov/technology/datagov/v3/ ? | 14 | | Digital.gov Content API | https://digital.gov/ | https://api.gsa.gov/technology/digitalgov/v1/ | 15 | | Discovery API | https://discovery.gsa.gov/api/ | https://api.gsa.gov/acquisition/discovery/v1/ | 16 | | [eMuseum API](http://gsa.github.io/eMuseum-API/) | https://gsafinearts.pbs.gsa.gov/emuseum/api/ | https://api.gsa.gov/real_estate/emuseum/v1/ | 17 | | [Go.USA.gov API](https://go.usa.gov/api) | http://go.usa.gov/api/ | http://api.gsa.gov/technology/go-usa-gov/ ? | 18 | | [Government Jobs API](http://search.digitalgov.gov/developer/jobs.html) | https://api.usa.gov/jobs/ | Done | 19 | | GSA Fleet Vehicles API | http://api.data.gov/gsa/fleet/vehicles | https://api.gsa.gov/transportation/fleet/v1/ | 20 | | GSA.GOV content API | https://www.gsa.gov/content-api | https://api.gsa.gov/technology/gsa-content/v2/ | 21 | | [Per Diem API](http://gsa.gov/portal/content/162379) | https://inventory.data.gov/api/action/datastore_search | https://api.gsa.gov/travel/perdiem/v2/rates/| 22 | | Product Service Codes (PSC) API - beta.sam.gov | https://api.sam.gov/prod/locationservices/v1/api | ------ | 23 | | Search.gov i14y API | https://i14y.usa.gov/api/v1/documents/ | https://api.gsa.gov/technology/searchgov/v2/documents/ | 24 | | Search.gov Search Results API | https://search.usa.gov/api/v2/search/ | https://api.gsa.gov/technology/searchgov/v3/results/ | 25 | | Search.gov Type-ahead API | https://search.usa.gov/sayt/ | https://api.gsa.gov/technology/searchgov/v2/suggestions/ | 26 | | Site Scanner API | ... | https://api.gsa.gov/technology/site-scanner/v1/domains/18f.gov/ | 27 | | [Sustainable Facilities Tool API](https://sftool.gov/developers) | https://api.data.gov/sftool/v1/ | https://api.gsa.gov/sustainability/sftool/v1/ | 28 | | [System for Award Management API](http://gsa.github.io/sam_api/sam/) | https://api.data.gov/sam/v1/ | https://api.gsa.gov/acquisitions/sam/v1/ | 29 | | [US Digital Registry API](https://usdigitalregistry.digitalgov.gov/) | https://api.gsa.gov/systems/digital-registry/v1/ | https://api.gsa.gov/technology/digital-registry/v1/ | 30 | -------------------------------------------------------------------------------- /api-design/overview.md: -------------------------------------------------------------------------------- 1 | _Under Construction. Please read on and share feedback or propose edits. [Tracking can be found here](https://github.com/GSA/api-standards/tree/master/api-design)._ 2 | 3 | ---------------- 4 | 5 | ## Background 6 | 7 | We have set up `https://api.gsa.gov/` as an umbrella domain for GSA's APIs. Using the [api.data.gov](https://api.data.gov/about/) service, we can organize some or all of GSA's APIs into consistent, unified endpoints without requiring them to use the same underlying system. In other words, we can invisibly route any endpoints that the agency builds into `https://api.gsa.gov/xxxxx`. 8 | 9 | ## Overall Proposal 10 | 11 | Use this page (or create others in this folder) to propose and deliberate on how to use the `https://api.gsa.gov/` base URL to unify the agency APIs. 12 | 13 | #### Benefits 14 | 15 | * Consistent API analytics for all involved GSA APIs. 16 | * Cleaner URLs (e.g. `https://api.gsa.gov/systems/assist/...` as opposed to `https://api.portal.fas.gsa.gov/assist-web/`). 17 | * Provides a better developer experience for the people we want using our APIs. 18 | * Easier to promote consistent norms from the agency API standards. 19 | * Makes future migrations easier since you can swap API infrastructure in and out from underneath the umbrella without changing urls. 20 | 21 | ## Ideas for a unified endpoint struction for the agency 22 | 23 | 24 | ### Option 1 25 | 26 | _This is a partial view meant to outline a proposed structure. Remember, we can customize everything after `.gov` to point to existing GSA endpoints however we want, so we can start building any of this . _ 27 | 28 | 29 | | URL | Result | 30 | |---|---| 31 | | https://api.gsa.gov/ | Redirects to the developer hub | 32 | | https://api.gsa.gov/data | Redirects to the developer hub | 33 | | https://api.gsa.gov/data/buildings/list | Endpoint for property directory API | 34 | | https://api.gsa.gov/data/travel/per-diem | Endpoint for per-diem API | 35 | | https://api.gsa.gov/systems/sam | Endpoint for the SAM API | 36 | | https://api.gsa.gov/systems/auctions | Endpoint for the Auctions API | 37 | | https://api.gsa.gov/systems/digital-registry | Endpoint for the Digital Registry API | 38 | | https://api.gsa.gov/documents | Redirects to the developer hub | 39 | | https://api.gsa.gov/documents?tag=press_release+pbs | Returns documents with the `press-release` and `pbs` tags | 40 | | https://api.gsa.gov/documents?id=32330 | Returns a specific document | 41 | 42 | 43 | ##### Proposed next steps 44 | 45 | 1. [Merge the PR](https://github.com/GSA/api-standards/pull/21) that creates this page. 46 | 2. Circulate it and more context to the agency API working group. 47 | 3. Gain consensus on the idea. 48 | 4. Have a team (perhaps team CTO) agree to chair the effort. 49 | 5. Update the above with the candidates for the first round of existing APIs that would be incorporated. 50 | 6. Give these existing APIs `api.gsa.gov` URLs. 51 | 7. Create and maintain a master directory of `api.gsa.gov` endpoints (it'd look like the above chart except be what exists in real life). 52 | 8. Update the API documentation for the first rounds APIs to use the `api.gsa.gov` URLs. 53 | 9. Create and maintain a sandbox section to the master directory of `api.gsa.gov` endpoints where anyone can propose further additions or refinements. 54 | 55 | -------------------------------------------------------------------------------- /codeinventory.json: -------------------------------------------------------------------------------- 1 | { 2 | "name": "api-standards", 3 | "description": "API Standards for GSA", 4 | "license": "https://github.com/GSA/api-standards/blob/master/LICENSE.md", 5 | "openSourceProject": 1, 6 | "governmentWideReuseProject": 1, 7 | "tags": [ 8 | "api", 9 | "gsa-api" 10 | ], 11 | "contact": { 12 | "email": "cto@gsa.gov" 13 | } 14 | } -------------------------------------------------------------------------------- /working_group/projects.md: -------------------------------------------------------------------------------- 1 | _Carrying this older material over from https://github.com/GSA/GSA-APIs. It's a better fit here._ 2 | 3 | 4 | ## Projects 5 | 6 | * Coordinate standards and best practices 7 | * Create a GSA API Standards 8 | * Help each other with feedback 9 | * Share code 10 | * Discuss GSA's future API work 11 | * Weigh Revamp of gsa.gov/developer 12 | * Ensure that gsa.gov/developer stays up to date 13 | * Normalize API documentation to github 14 | * An intranet developer hub for internal only APIs. ?insite.gsa.gov/developer? 15 | * Process [open issues](https://github.com/GSA/GSA-APIs/issues) 16 | 17 | 18 | ## Other Ideas 19 | * Review Website Analytics 20 | * Review api analytics 21 | * Review and publish the data coming in through the feedback pane on the bottom right of gsa.gov/developer 22 | * Memorialize regular workflows, such as requesting DNS setup and SSL certs 23 | 24 | 25 | --------------------------------------------------------------------------------