Jump to: navigation, search

Difference between revisions of "Blueprint-os-api-docs"

(BLUEPRINT: OpenStack API Complete Reference web pages (revised))
(BLUEPRINT: OpenStack API Guide (new))
Line 42: Line 42:
 
* Continuous Integration (CI) Developer Documentation
 
* Continuous Integration (CI) Developer Documentation
 
* Programming OpenStack Compute API with Shell and Python
 
* Programming OpenStack Compute API with Shell and Python
* API Reference/s
+
* API Reference/s<br />
 +
 
 +
 
 +
'''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) ==
 
== BLUEPRINT: OpenStack ''project'' API Reference/s (delete) ==

Revision as of 15:41, 22 September 2013

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 provides 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 Introduces admin users to administrative tasks, and ways of interacting with the cloud. Provides 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.
  • 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


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

  • 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)
  • Source reference information from WADL files.
  • Exclude guidance information or feature descriptions that are longer than one sentence (this goes in the OpenStack API Guide).

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.