OpenAPI and eBay RESTful APIs

As part of eBay's RESTful APIs, we're providing eBay API Contracts for them in the increasingly popular OpenAPI format. This page is an overview of OpenAPI, and how to use its associated Swagger tools to generate client libraries for eBay APIs in multiple programming languages.

Subtopics

What are the OpenAPI specification and eBay API Contracts?

The OpenAPI Specification (formerly Swagger Specification) defines a format for describing REST APIs. eBay API Contracts are descriptions of eBay's RESTful APIs that follow the OpenAPI specification. An eBay API Contract defines every aspect of its API, and is a contract to users for that definition. It includes:

  • Available endpoints
  • HTTP operations on each endpoint (e.g. GET /users, POST /users)
  • Parameters for each operation
  • Input and output for each operation
  • Authentication methods
  • Contact information, license, terms of use, etc.

We write eBay API Contracts in both YAML and JSON.

eBay is gradually rolling out beta contracts for our RESTful APIs in order to make API integration easier across multiple technology stacks.

They're beta so we can be cautious with our first OpenAPI format launch, get feedback and do any needed fixes, and then switch to release status.

Currently, many eBay RESTful APIs have Contracts, with both JSON and YAML versions linked to in the left sidebar on their eBay Developers Program homepages. When an API goes to a new version, both its YAML and JSON Contract versions are updated to sync with the new version. For an example Contract, see the Browse API in the Buy APIs.

eBay was one of the first to publish OpenAPI 3.0 compliant Contracts, after Open API 3.0's July, 2017 release. Some eBay APIs have a Contract for each of the OpenAPI v2 and v3 specifications. Improvements in 3.0 from 2.0 include:

  • Support for describing callbacks
  • Links to express relationships between operations
  • Webhooks
  • Enhanced examples
  • Improved parameter descriptions
  • Better multipart document handling
  • Support for templated server URLs
  • Support for semantic versioning

A detailed list is in OpenAPI Specification v3.

What is Swagger?

Swagger is a set of open source tools for working with OpenAPI Contracts, including:

  • Swagger Editor for writing Contracts in a browser.
  • Swagger UI for viewing Contracts as interactive documentation.
  • Swagger Codegen for generating server stubs and client libraries from a Contract in multiple languages.

Of these, developers use Swagger Codegen with existing eBay API Contracts. Swagger Editor is what API designers use to write OpenAPI compliant Contracts; eBay's already done that for you. With Swagger UI you can use our Contracts to generate documentation, but that's much the same as looking at our RESTful APIs' reference materials. Also, Swagger UI does not necessarily show errors or constraints (such as string length, use cases, etc.), so we recommend using our API reference docs over what Swagger displays.

Swagger Codegen

Using an eBay API Contract, Swagger Codegen can generate client libraries for many different languages. By generating a client library, you can easily call the API methods from your chosen development language, such as Python or Java.

Supported languages include Android, bash, C#, Clojure, Go, Groovy, Haskel, Java, JavaScript, Perl, PHP, Python, Ruby, Scala, Swift, and many more. To see the complete list, run java -jar acodegen-jar-file.jar in a terminal window.

Codegen also creates server stubs for each operation defined in the Contract. When you make a remote procedure call (RPC) with a server stub, it:

  • Unpacks input arguments from their transmitted formats
  • Calls the method's actual implementation on the server
  • Puts the method's output values into transmittable form

Installing Swagger Codegen

Codegen's source code is available on GitHub, and you must have Java version 7 or higher installed on your machine to run Codegen.

Use either Homebrew (Mac or Linux environments) or Maven Central to install Codegen:

  • Homebrew:
    1. Run brew install swagger-codegen
  • Maven Central:
    1. Go to this Maven Central folder
    2. Select a version to install (we recommend the latest version)
    3. Get and run the chosen version's executable .jar file by either:
      • Clicking on it to download it, then running it
      • Using wget; wget .jar_file_URL

Using Swagger Codegen via the command line

The following subsections outline how to run Swagger commands from the command line, get help on commands, and generate code stubs.

Running commands and getting help

The general syntax for running a Codegen command from a terminal window is:

$ java -jar swagger-codegen-cli-2.2.3.jar command_name

Here, the argument after -jar is your Codegen .jar file. For simplicity, we use the file name to codegen.jar in the rest of our examples. This file name is followed by the Codegen command you want to run.

Use the following Help command to retrieve a list of Codegen commands:

$ java -jar codegen.jar help

Here's a list of common commands and their summaries, as returned by the Help command:

  • config-help: Config help for chosen language
  • generate: Generate code with chosen language
  • help: Display help information
  • help [command]: More information about the specified command
  • langs: Shows available languages
  • meta: MetaGenerator. Generator for creating a new template set and configuration for Codegen based on specified language. Output has default templates to include.
  • validate: Validate specification
  • version: Show version information

Generating code

To use an OpenAPI file to generate a stubs in the language of your choice, use the generate command with -i and -l arguments.

For example, the following command uses an OpenAPI file to generate the Java stubs for an application that runs pet stores, located at the given URL:

java -jar codegen.jar generate -i http://petstore.swagger.io/v2/swagger.json -l java

This command creates a lot of files when it generates the stub files, both in the current working directory and in four sub-directories. Here's a breakdown of the Java files that Codegen creates:

  • src: Java classes to implement the calls to the API
  • docs: Markdown documentation generated from the resulting Java classes
  • gradle: Gradle is an open source build automation system built on Apache Ant and Apache Maven concepts that uses a Groovy-based domain-specific language (DSL) for declaring the project configuration
  • .swagger-codegen: Only contains a VERSION file

A key initial file is README.md, which documents:

  • Requirements for building the generated API client library
  • Installing the API client library
  • Getting Started example code, showing what calling a basic command looks like
  • API Endpoint, Model, and Authorization documentation
  • Usage recommendations

In more detail, the API Endpoint documentation gives a brief description of each method defined in the client library:

  • Class the method's defined in
  • Method's name
  • Corresponding HTTP request in the REST API
  • Brief functionality description

Further, clicking on a method's name takes you to a page with detailed documentation about the method's class, including documenting for each class method:

  • Short description
  • Example method call using the client library
  • Parameters
  • Return type
  • Authorization details
  • HTTP request headers used by the underlying RESTful API call

The Model documentation describes each class' properties and any defined Enums.

Authorization documentation describes all authentication schemes for an API. For OAuth, it lists the API's Authorization URL and scopes.

For more information...

The complete OpenAPI Specification is on GitHub.

The Open API Initiative (OAI) controls and administers the OpenAPI specification. OAI is a Linux Foundation project, of which eBay is a member. Its website is at www.openapis.org

The Swagger website has complete information about the OpenAPI format and its Swagger tools.

We recommend starting at the Specification page, after which you should move on to the Swagger tools page. The latter page covers alternate methods of installing and using Codegen than those presented here.

Next, look at Codegen's README.md file on GitHub. This covers Codegen's various commands and their arguments in detail, as well as how to customize Codegen and its output. It also has a long list of, as it heads the section, Presentations/Videos/Tutorials/Books on Codegen with links to the material.