Difference between revisions of "Blueprint-os-api-docs"
| Line 1: | Line 1: | ||
| − | + | * '''Launchpad Entry''': [https://blueprints.launchpad.net/openstack-manuals/+spec/blueprint-os-api-docs/ Design for OpenStack API Docs] | |
| + | * '''Created''': Diane Fleming | ||
| + | * '''Contributors''': | ||
| − | + | == Summary == | |
| − | + | This blueprint describes a plan to create documentation for OpenStack application developers and contributors. | |
| − | + | This documentation will explain API concepts and provide guidance for developers who want to extend the OpenStack APIs or write applications that run on an OpenStack cloud. It will also provide complete reference information for each OpenStack API, including API syntax, descriptions of required and optional request parameters, descriptions of response fields, and request and response code examples. | |
| − | + | This documentation will provide 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. | |
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| + | <br /><br /> | ||
| − | |||
| − | === OpenStack API Guide (new) | + | The planned documentation includes: |
| + | {| class="wikitable" | ||
| + | |- | ||
| + | ! Document !! Purpose | ||
| + | |- | ||
| + | | OpenStack API Guide || Introduces developers to API concepts, common tasks, and ways of interacting with the OpenStack APIs. <br /> | ||
| + | |||
| + | |- | ||
| + | | OpenStack API Complete Reference web pages || Introduces admin users to administrative tasks, and ways of interacting with the cloud. <br /> | ||
| + | |||
| + | * 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. | ||
| + | |||
| + | |} | ||
| + | |||
| + | |||
| + | |||
| + | |||
| + | == BLUEPRINT: OpenStack API Guide (new) == | ||
'''Purpose''' | '''Purpose''' | ||
| − | + | ||
'''Source material''' | '''Source material''' | ||
| Line 32: | Line 48: | ||
* API Reference/s | * API Reference/s | ||
| − | == | + | == BLUEPRINT: OpenStack ''project'' API Reference/s (delete) == |
'''Strategy''' | '''Strategy''' | ||
| Line 38: | Line 54: | ||
* Move material from these books into the WADL files that source the API Complete Reference web pages. | * Move material from these books into the WADL files that source the API Complete Reference web pages. | ||
| − | == | + | == BLUEPRINT: OpenStack API Complete Reference (web pages) == |
'''Purpose''' | '''Purpose''' | ||
Revision as of 15:29, 22 September 2013
- Launchpad Entry: Design for OpenStack API Docs
- Created: Diane Fleming
- Contributors:
Contents
Summary
This blueprint describes a plan to create documentation for OpenStack application developers and contributors.
This documentation will explain API concepts and provide guidance for developers who want to extend the OpenStack APIs or write applications that run on an OpenStack cloud. It will also provide complete reference information for each OpenStack API, including API syntax, descriptions of required and optional request parameters, descriptions of response fields, and request and response code examples.
This documentation will provide 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.
The planned documentation includes:
| Document | Purpose |
|---|---|
| OpenStack API Guide | Introduces developers to API concepts, common tasks, and ways of interacting with the OpenStack APIs. |
| OpenStack API Complete Reference web pages | Introduces admin users to administrative tasks, and ways of interacting with the cloud.
|
BLUEPRINT: OpenStack API Guide (new)
Purpose
Source material
- Python Developer Documentation
- Language Bindings Documentation
- Continuous Integration (CI) Developer Documentation
- Programming OpenStack Compute API with Shell and Python
- API Reference/s
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)
Purpose
- Provide one reference page for each project: Compute, Image Service, Identity Service, Object Storage, Networking, Orchestration, and Block Storage Service. (already implemented)
- Source reference information from WADL files.
- Pull material from existing API Reference/s into WADL files so everything is single-sourced from WADL files.
- Provide developers with searchable and comprehensive Web pages that list API methods and parameters, with examples for each.
- Exclude guidance information (this goes in the OpenStack API Guide), installation instructions, or feature descriptions that are longer than one sentence.
Source material
- API Reference - sourced from WADL files
