Blueprint-os-api-docs
- Launchpad Entry: Design for OpenStack API Docs
- Created: Diane Fleming
- Contributors:
- Related Blueprint: Blueprint-restructure-documentation
Contents
- 1 Strategy
- 2 Summary
- 3 Audience
- 4 BLUEPRINT: OpenStack API Guide (new)
- 4.1 CHAPTER: API Concepts
- 4.2 CHAPTER: How to Access the APIs
- 4.3 CHAPTER: Authentication
- 4.4 CHAPTER: Request/Response Types
- 4.5 CHAPTER: Links and References
- 4.6 CHAPTER: Paginated Collections
- 4.7 CHAPTER: Efficient Polling with the Changes-Since Parameter
- 4.8 CHAPTER: Limits
- 4.9 CHAPTER: Versions
- 4.10 CHAPTER: Extensions
- 4.11 CHAPTER 10: Faults
- 4.12 COMMON Glossary
- 5 BLUEPRINT: OpenStack project API Reference/s (delete)
- 6 BLUEPRINT: OpenStack API Complete Reference web pages (revised)
Strategy
- Eliminate the existing API References: http://docs.openstack.org/api/api-ref-guides.html.
- Add an API Guide that describes API concepts, general information, and ways to access the APIs.
- Move material currently in the API Reference/s into the WADL files to source the API Complete Reference pages. One web page for each OpenStack project. Source code samples from nova code base where possible.
End result: One API Reference page for each project and one API Guide.
Summary
| Document | Change | Purpose |
|---|---|---|
| OpenStack API References | Delete | Get rid of the existing API References (http://docs.openstack.org/api/api-ref-guides.html).
Explains API concepts and provide guidance for developers who want to extend the OpenStack APIs or write applications that run on an OpenStack cloud. |
| OpenStack API Guide | New | Introduces developers to API concepts, common tasks, and ways of interacting with the OpenStack APIs.
Explains API concepts and provide guidance for developers who want to extend the OpenStack APIs or write applications that run on an OpenStack cloud. |
| OpenStack API Complete Reference web pages | Revised | Provides developers with searchable and comprehensive Web pages that list API methods and parameters, with examples for each. |
Audience
This blueprint describes a plan to create documentation for OpenStack application developers and contributors.
In addition to providing documentation to experienced developers, this documentation will also describe the next step for end users who know how to use the dashboard and client commands to interact with an OpenStack cloud and who want to progress to using the APIs directly or indirectly through cURL commands or open SDKs.
BLUEPRINT: OpenStack API Guide (new)
Purpose
- Introduces developers to API concepts, common tasks, and ways of interacting with the OpenStack APIs.
- Provides guidance for developers who want to extend the OpenStack APIs or write applications that run on an OpenStack cloud.
Source material
- Python Developer Documentation
- Language Bindings Documentation
- Continuous Integration (CI) Developer Documentation
- Programming OpenStack Compute API with Shell and Python
- API Reference/s
Outline
CHAPTER: API Concepts
Cull material from existing API Reference/s. Also talk about how to access the APIs.
CHAPTER: How to Access the APIs
The API Complete Reference for a project will include access information in the form of listing the service type that should be used to locate the service endpoint(s) in the service catalog returned by Authenticate. It will also include information about text encodings, content types, etc.
CHAPTER: Authentication
Cull material from existing API Reference/s. Provide working examples.
The Identity Service Authenticate method will describe the authentication process. The summary/overview section of the API reference for a specific project can then mention that all calls for that project require the inclusion of an X-Auth-Token header, with a value obtained from the Authenticate method (linking back to the API complete reference for the identity project). Additional information in the API Guide, which is not directly expressed in the API Complete Reference, would be recommended client practices regarding re-authentication of expired tokens.
CHAPTER: Request/Response Types
Cull material from existing API Reference/s. Provide working examples.
CHAPTER: Links and References
Cull material from existing API Reference/s. Provide working examples.
CHAPTER: Paginated Collections
Cull material from existing API Reference/s. Provide working examples.
CHAPTER: Efficient Polling with the Changes-Since Parameter
Cull material from existing API Reference/s. Provide working examples.
CHAPTER: Limits
Cull material from existing API Reference/s. Provide working examples.
The API Complete Reference will include information about return values indicating that an API call failed due to an artificial limit (e.g. quota or rate limit). Based on this information, clients can be written to perform well regardless of the actual limits that are in place. Additional information in the API Guide might include details about the limits in place for a specific vendor’s implementation of the product.
CHAPTER: Versions
Cull material from existing API Reference/s. Provide working examples.
CHAPTER: Extensions
Cull material from existing API Reference/s. Provide working examples.
CHAPTER 10: Faults
Cull material from existing API Reference/s. Provide working examples.
All available information about faults for an API call should appear in the API Complete Reference for that call. This is covered in more detail under the Responses section of The JSON Checklist.
COMMON Glossary
BLUEPRINT: OpenStack project API Reference/s (delete)
Strategy
Eliminate these books:
- Block Storage Service API v2 Reference
- Compute API v2 and Extensions Reference
- Identity Service API v2.0 Reference
- Networking API v2.0 Reference
- Image Service API v2 Reference
- Image Service API v1 Reference
- Object Storage API v1 Reference
- Programming Compute API with Shell and Python, 1st ed.
Move material from these books into the WADL files that source the API Complete Reference web pages.
BLUEPRINT: OpenStack API Complete Reference web pages (revised)
Purpose
- Provide developers with searchable and comprehensive Web pages that list API methods and parameters, with examples for each.
- Provide one reference page for each project: Compute, Image Service, Identity Service, Object Storage, Networking, Orchestration, and Block Storage Service (already implemented). From Sam Harwell: My big concern is the size of the resulting complete reference page. If the entire API for a product is presented on a single page, it will not be friendly for mobile devices, or for hyper-linking users to information about specific calls as part of a community answer. In addition to the URI information and the examples, all of the information from the JSON/REST checklist is critical to the lasting value of the complete API reference.
- Before deleting the API References, pull reference material from them into WADL files.
- Source reference information for the API Reference pages from WADL files (already implemented, but WADL files will be updated with more information).
- Review and improve the existing content so that it includes complete descriptions, request and response parameters, and tested code samples.
- Use Sam Harwell's JSON/REST checklist to improve the documentation. In a separate effort, Sam Harwell and David Cramer plan to identify where each piece of information in the JSON/REST checklist fits in a WADL file. Then, David plans to enhance clouddocs-mvn-plugin so that it validates WADL files for comprehensiveness and pulls more information from WADL files for display.
Source materials
- API Reference - sourced from WADL files
- API Reference/s - Pull material from existing API Reference/s into WADL files so everything is single-sourced from WADL files.
