Application Developer Guides - aka API Guides

updated: 2018-12-06 13:55

Application Developer Guides - aka API Guides

https://blueprints.launchpad.net/openstack-manuals/+spec/app-guides-mitaka-vision

We want to build comprehensive application developer documentation for public-facing OpenStack REST APIs. These guides aim to empower consumers to successfully build cloud-native applications. Each comprehensive guide, delivered on developer.openstack.org, will contain a collection of conceptual articles, reference information, and how-to articles.

Problem description

For years, we have published API references. However, application developers also need conceptual, how-to, and best practice information.

Goals

To better serve this developer.openstack.org audience, we plan to:

  • Update the landing and web pages to make developer.openstack.org more usable
  • Give application developers information based on their language of choice
  • Source information about service capabilities and REST APIs through each service repository itself
  • Ensure that the “First App on OpenStack” is a complete and easy-to-use first guide
  • Automate the generation of API reference information
  • Create excellent, helpful, accurate, sufficient app developer guides
  • Standardize with the API Working Group doc guidelines in mind
  • Organize the guides around developer tasks and workflow rather than around services

Proposed change

With these general guidelines in mind, let’s build a new guide from multiple sources with this outline:

  • Introduction to OpenStack REST APIs

  • Build your First App on OpenStack

  • Discover OpenStack services, workflows, and resources

    • Authenticate as a user
    • Inspect the service catalog
    • Decide what services and resources you need
      • Images
        • Manage images
      • Compute instances (VMs)
        • Understand flavors and images
        • Launch an instance
        • Provide user data to an instance
        • Manage access and security
          • Use keypairs
          • Use security groups
        • Migrate instances
      • Networks
        • Create networks, ports, routers, subnets
        • Load balance across servers
      • Block Storage
        • Attach volumes with block storage
        • Transfer a volume from server-to-server
      • Object Storage

  • Deploy apps on OpenStack

  • Troubleshoot apps on OpenStack

  • Libraries and Software Development Kits

    • Python
    • Go
    • .Net
    • Java
    • nodejs
    • Ruby
    • PHP

  • API Complete References Based on Swagger, each method should have the following information:

    • Method (GET/PUT/POST/PATCH/HEAD/DELETE)
    • Resource (identified by the URL)
    • Request parameters, type and description including whether it is optional
    • Request headers including media-type, content-type, accept, and others
    • Response headers (for some APIs)
    • Responses including types and description
    • Example request headers and body
    • Example response headers and body
    • Status codes: success and error response codes
    • Resource model: data types that can be consumed and produced

    These services are scoped for this team’s work this release:

    • Identity
    • Compute
    • Images
    • Networks
    • Block Storage
    • Object Storage

  • Best practices for apps on OpenStack

How will each section be sourced?

  • API Quick Start in the api-site repository
  • First App on OpenStack in the api-site repository
  • Refresh the landing page in the api-site repository
  • api-guide folder in each OpenStack service repository, such as nova
  • api-ref info containing migrated Swagger/RST source files

How will consumers find and read these articles? From:

and so on as we fill out the outline above with content.

What about projects not in this outline?

This outline suggests a pattern for subsequent projects to follow. This outline creates a framework for application developer docs. We expect trove, sahara, ironic, and other projects to follow this pattern to best serve their consumers.

Alternative

We could continue to produce specifications on specs.openstack.org combined with API reference information and links to SDKs.

However as the OpenStack ecosystem expands, we want to foster the best practices for application developers by providing the best experience through the http://developer.openstack.org.

Implementation

With the completion of both the WADL to Swagger/RST migration proof-of-concept and the nova repository to developer.openstack.org site publication proof-of-concept, the following Work items section describes the remaining implementation tasks.

Assignees

Primary assignee:
russellsim Russell Sim

Other contributors:

  • annegentle Anne Gentle
  • etowes Everett Toews
  • sdague Sean Dague
  • kbhawkey Karen Hawkey
  • fifieldt Tom Fifield

Work items

  • Landing and web pages
    • Revise landing page for developer.openstack.org - russellsim
    • Create landing page for developer.openstack.org/sdks - russellsim
    • Create web pages for developer.openstack.org/sdks/python/openstacksdk - etoews
  • Content
    • Complete First App on OpenStack matrix of SDK support (complete). Tom should keep communicating about it as he is. - fifieldt
    • Ensure that APIs that support micro-versions display that information - russellsim
    • Document the API guides system for teams, including how to write, where to write, what to write, to use the framework as it is intended - annegentle
    • Remove obsolete content from the SDK landing page. Both the .NET and PHP projects on the current landing page have been removed due to inactivity, see https://wiki.openstack.org/wiki/Stackforge_Namespace_Retirement#Inactive_Projects_to_Retire - annegentle
    • Create a new core review team for API documentation specifically including members of the API working group - annegentle
  • Publication jobs
    • Write publishing jobs to statically copy Swagger/RST reference documentation from fairy-slipper to developer.openstack.org - russellsim, annegentle, and kbhawkey
    • Publish the Python SDK OpenStackSDK docs to developer.openstack.org - etowes
  • Communication
    • Communicate the January 16th WADL freeze date for cut over to Swagger/RST - annegentle
    • Communicate what teams must do to follow this pattern - annegentle
    • Write a specification for the infrastructure project so that they understand our need for a server rather than static content for developer.openstack.org - russellsim

Dependencies

Testing

These deliverables use the tested openstackdocstheme Sphinx theme. No additional testing resources are expected at this time.

updated: 2018-12-06 13:55
Creative Commons Attribution 3.0 License

Except where otherwise noted, this document is licensed under Creative Commons Attribution 3.0 License. See all OpenStack Legal Documents.

questions?

docs-specs