Difference between revisions of "Blueprint-os-api-docs"
(→Summary) |
(→BLUEPRINT: OpenStack API Complete Reference web pages (revised)) |
||
| Line 91: | Line 91: | ||
* Sources reference information from WADL files. | * Sources reference information from WADL files. | ||
* Pulls material from existing API Reference/s into WADL files so everything is single-sourced from WADL files. | * Pulls material from existing API Reference/s into WADL files so everything is single-sourced from WADL files. | ||
| − | * Review and improve the existing output so that it includes complete descriptions, request and response parameters, and tested code samples. | + | * Review and improve the existing output so that it includes complete descriptions, request and response parameters, and tested code samples.<br /> |
| + | <br /> | ||
| + | |||
'''Source materials''' | '''Source materials''' | ||
* API Reference - sourced from WADL files | * 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. | + | * API Reference/s - Pull material from existing API Reference/s into WADL files so everything is single-sourced from WADL files.<br /> |
| + | <br /> | ||
Revision as of 15:47, 22 September 2013
- Launchpad Entry: Design for OpenStack API Docs
- Created: Diane Fleming
- Contributors:
Contents
- 1 Audience
- 2 Summary
- 3 BLUEPRINT: OpenStack API Guide (new)
- 3.1 CHAPTER 1: API Concepts
- 3.2 CHAPTER 2: Authentication
- 3.3 CHAPTER 3: Request/Response Types
- 3.4 CHAPTER 4: Links and References
- 3.5 CHAPTER 5: Paginated Collections
- 3.6 CHAPTER 6: Efficient Polling with the Changes-Since Parameter
- 3.7 CHAPTER 7: Limits
- 3.8 CHAPTER 8: Versions
- 3.9 CHAPTER 9: Extensions
- 3.10 CHAPTER 10: Faults
- 3.11 COMMON Glossary
- 4 BLUEPRINT: OpenStack project API Reference/s (delete)
- 5 BLUEPRINT: OpenStack API Complete Reference web pages (revised)
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.
Summary
The planned documentation includes:
| Document | Purpose |
|---|---|
| OpenStack API Guide | 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 | Provides developers with searchable and comprehensive Web pages that list API methods and parameters, with examples for each. |
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 1: API Concepts
Cull material from existing API Reference/s. Also talk about how to access the APIs.
CHAPTER 2: Authentication
Cull material from existing API Reference/s. Provide working examples.
CHAPTER 3: Request/Response Types
Cull material from existing API Reference/s. Provide working examples.
CHAPTER 4: Links and References
Cull material from existing API Reference/s. Provide working examples.
CHAPTER 5: Paginated Collections
Cull material from existing API Reference/s. Provide working examples.
CHAPTER 6: Efficient Polling with the Changes-Since Parameter
Cull material from existing API Reference/s. Provide working examples.
CHAPTER 7: Limits
Cull material from existing API Reference/s. Provide working examples.
CHAPTER 8: Versions
Cull material from existing API Reference/s. Provide working examples.
CHAPTER 9: Extensions
Cull material from existing API Reference/s. Provide working examples.
CHAPTER 10: Faults
Cull material from existing API Reference/s. Provide working examples.
COMMON Glossary
BLUEPRINT: OpenStack project API Reference/s (delete)
Strategy
- Eliminate these books.
- 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
- Provides developers with searchable and comprehensive Web pages that list API methods and parameters, with examples for each.
- Provides one reference page for each project: Compute, Image Service, Identity Service, Object Storage, Networking, Orchestration, and Block Storage Service. (already implemented)
- Sources reference information from WADL files.
- Pulls material from existing API Reference/s into WADL files so everything is single-sourced from WADL files.
- Review and improve the existing output so that it includes complete descriptions, request and response parameters, and tested code samples.
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.
