appveyor-swagger

Unofficial AppVeyor REST API Swagger Definition

This project aims to provide a Swagger/OpenAPI definition of the AppVeyor REST API. It is neither supported nor endorsed by AppVeyor. Any differences between this definition and the AppVeyor REST API are errors in this definition and users are encouraged to report the issue.

Documentation

The documentation generated from the Swagger definition is available in the following formats:

• ReDoc: AppVeyor API Docs (Supports discriminator)
• Swagger UI: AppVeyor API Docs
• Bootprint: AppVeyor API Docs

Installation

The Swagger definition can be installed as an an npm package by running:

npm install appveyor-swagger

It can then be used in Node.js projects with:

var appveyorSwagger = require('appveyor-swagger');

Test Client

There is a AppVeyor API Client in Java which is generated from the definition in this project and used for demonstration and testing purposes. It is a good example of how to generate and use a client based on this definition.

Implementation Notes

Versioning

The AppVeyor REST API does not provide any public versioning scheme that I am aware of. Since versioning is necessary, both in the OpenAPI specification file and in the npm package, this package attempts to apply the rules of Semantic Versioning 2.0.0 to code generated from this OpenAPI definition to determine appropriate version numbers.

Since generated code varies based on the code generator and settings used, the definition of what constitutes a backward-compatible API change is subjective. The version numbering will be conservative, such that the major version number is incremented for potentially- and selectively-incompatible generated API changes. Users who encounter changes which violate semantic versioning expectations are encouraged to report the issue so the version can be incremented accordingly.

Schema Names

The schema names used in the definition are based on the names returned in the XML API responses, where those names are not confusing and do not conflict with the requirements imposed by discriminator. (The OpenAPI Spec requires discriminator property values match schema names).

Schema Strictness

There are many trade-offs between the schema strictness and the usability, clarity, and flexibility of the code generated by the schema. This project attempts to make the types as strict as possible without compromising usability and clarity. This provides the most type safety (for strictly typed languages) and protection against accidental API misuse. Specific choices are described below.

With Schema Types

The DeploymentEnvironment, Project, and Role schemas each have a second schema which defines additional properties (DeploymentEnvironmentWithSettings, ProjectWithConfiguration, RoleWithGroups). The advantage to having separate types is both clarity in the generated documentation and protection against misuse. For example, trying to update a project using the Project instead of ProjectWithConfiguration can be caught either at compile time or before the request is made. The disadvantage is that since the generated With classes do not implement or inherit from the class/interface of their parent schemas and do not provide copy constructors between them, using them becomes more painful. I would appreciate feedback about this trade-off in real-world use cases.

PUT vs GET Schema Types

PUT schemas could be defined separately from the GET types in several cases. This would allow making most properties required in the GET types, which could result in non-nullable/non-optional codegen in some languages (although it does not in any that I'm currently aware of). The down-side is that unless the codegen includes an easy way to translate data between these types, doing a GET+modify+PUT becomes more painful than it should be. So this has been not been done.

Polymorphism

swagger-polymorphic.yaml attempts to provide stricter type definitions by applying polymorphism using the discriminator property. Most tools provide limited or no support for this property. Therefore, this file is mostly kept for reference and in the hopes that future tools may be able to make use of it.

Polymorphic types are problematic for several reasons, not least of which is the requirement that Schema name match the discriminator property value, which can cause collisions and require ugly names. OAI/OpenAPI-Specification#403 There are various extensions available:

• AutoRest uses x-ms-discriminator-value
• Swagger Codegen has an open PR to use x-discriminator-value

There are also plans to support oneOf and anyOf in OpenAPI v3.0 OAI/OpenAPI-Specification#741 along with adding a value to type map for discriminator. This may solve the above issues.

Shared responses

The next version of the spec includes support for version ranges using 4XX notation (OAI/OpenAPI-Specification#638). There is also discussion of including a mechanism for defining default responses in OAI/OpenAPI-Specification#521 and OAI/OpenAPI-Specification#563 Unfortunately, since neither of these is supported in OpenAPI v2.0, the definition in this project contains a redundant error response definition for error for each API path.