Conjur has a public reuseable OpenAPI v3+ specification

[sgnn7]

Project Outcome

Reusable Community-level OpenAPI v3+ specification describing Conjur API interfaces that can be used to auto-generate client code and documentation.

Project Scope

• Importable specification artifact(s)
• Client artifacts in some languages (TBD but Golang, Python3, and Ruby are likely) generatable from specification artifacts
• Automated test framework & CI/CD pipeline
• Initial public release

Out of scope:

• Changing Conjur server code to use code generated by this spec
• Auto-generating documentation based on the specification
• Auto-generating API spec from server code
• Including DAP-only endpoints
• Generating a v2 specification

Feature Details

Problem Statement

Conjur currently has a limited SDK comprised of a Command Line Interface (CLI) and client libraries written in Python 3, Golang, Ruby, .Net Framework 4.5, and Java 8. Each client supports a different subset of API routes / features than any other.

In addition, currently when the Conjur API is changed, a docs issue is required to update the official API documentation, which has the potential to leave a mismatch between the published API documentation and the actual API.

With an OpenAPI specification for Conjur, we can improve the Conjur SDK and get us on a path to having a better link between our actual API and its documentation.

Having a public OpenAPI spec for Conjur enables:

• Automatic client generation, so that our Conjur SDK can be consistent across clients, is easier to maintain as the API changes, and is easy to expand by adding support for new clients – even for community members.
• Automatic API documentation generation that is consistent across CyberArk APIs, which are also moving toward OpenAPI Spec-based documentation; this will also make it easier to maintain documentation that is consistent with the API.
• Lower maintenance costs for the Conjur SDK, since if we leverage this to replace existing clients, we’ll have a more consistent pattern for maintaining each client even though they are written in other languages.

Draft What's New Content

We now have a public OpenAPI v3 specification for the Conjur API. With the release of this spec, we now provide a standardized, machine-readable version of the API that can be used to automatically generate API documentation, to generate Conjur client libraries in your language of choice, and to facilitate exploring the Conjur API using popular tools like Postman. Internally, we’ll be using this OpenAPI spec to build a better, more consistent, always up-to-date Conjur SDK comprised of clients in the most popular languages with comprehensive automated test coverage. This release simplifies end users’ ability to interact with the Conjur API, and will enable the continued expansion of Conjur integrations so that Conjur works natively with the most popular software development tools.

The specification is compatible with Conjur OSS v1.11+.

User Stories

Enabling Contributions

As a Conjur subject matter expert or CyberArk partner
I want up-to-date documentation on how to use and interact with the Conjur API
So that I can extend Conjur by building integrations with other popular tools

As a CyberArk Developer, or a developer working on apps that use Conjur/DAP
I want instructions for generating client code for my language of choice
So that I can build a client for Conjur in the language of my choice quickly

Exploring Conjur

As a Conjur/DAP User, CyberArk Developer, or a developer working on apps that use Conjur/DAP
I want an up-to-date OpenAPI v3 specification
So that I can read the OpenAPI spec and understand the Conjur endpoints and how they work

As a Conjur/DAP User, CyberArk Developer, or a developer working on apps that use Conjur/DAP
I want an OpenAPI v3 specification that is clear about the corresponding Conjur version
So that I know which version of the spec is relevant for my specific Conjur instance

As a Conjur/DAP User, CyberArk Developer, or a developer working on apps that use Conjur/DAP
I want up-to-date documentation on the Conjur API endpoints
So that I have a human-readable way of understanding the Conjur API endpoints and how they work

As a Conjur/DAP User, CyberArk Developer, or a developer working on apps that use Conjur/DAP
I want an up-to-date OpenAPI v3 specification
So that I can use the spec to understand how to interact with Conjur via hand-crafted direct-to-API calls in the language of my choice (curl, Python’s urllib, Golang’s net/http, etc.) .

As a Conjur/DAP User, CyberArk Developer, or a developer working on apps that use Conjur/DAP
I want an up-to-date OpenAPI v3 specification
So that I can import it into tooling (like Postman) and experiment with the Conjur API

Managing Conjur

As a operations developer or admin
I want an up-to-date OpenAPI v3 specification
So that I can easily include the Conjur API in my existing Kong, Apigee, or AWS API gateway.

Access to Consistent, Up-to-Date Clients

As a Conjur/DAP User, CyberArk Developer, or a developer working on apps that use Conjur/DAP
I want a client library available in my favorite language
So that I can update my application code to interact with Conjur by using a language-specific library, so that I don’t have to implement direct-to-API calls myself

As a Conjur/DAP User, CyberArk Developer, or a developer working on apps that use Conjur/DAP
I want the Conjur client I use to be updated with recent API changes
So that I can use new features in the client not long after when they’re available on the server

[izgeri]

The end result of this will be a released version of this product - the release AC should include:

• There is a release that our users can see from the main releases page
  • There is an annotated tag in the repo matching that version
  • Spec is included in that release
  • (TBD) Additional files (client libraries, license, readme, changelog) are included in the release