https://github.com/cloudy-sky-software/cloud-provider-api-conformance
A spec for cloud providers to make their REST APIs compatible for generating a native Pulumi provider.
https://github.com/cloudy-sky-software/cloud-provider-api-conformance
Last synced: 5 months ago
JSON representation
A spec for cloud providers to make their REST APIs compatible for generating a native Pulumi provider.
- Host: GitHub
- URL: https://github.com/cloudy-sky-software/cloud-provider-api-conformance
- Owner: cloudy-sky-software
- License: mit
- Created: 2023-12-05T11:37:46.000Z (over 2 years ago)
- Default Branch: main
- Last Pushed: 2024-09-30T06:00:41.000Z (over 1 year ago)
- Last Synced: 2025-01-19T08:32:27.022Z (over 1 year ago)
- Size: 14.6 KB
- Stars: 4
- Watchers: 2
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Pulumi Resource Provider API Conformance
> ⚠️ This document is actively evolving.
This repository contains a conformance test and guidelines (COMING SOON!) that describe how resource providers can ensure a highly-compliant OpenAPI document in order to generate native [Pulumi providers](./pulumi.md). Native Pulumi providers are Pulumi SDKs that rely on the provider's API and communicate with them using HTTP requests.
Following the guidelines outlined in this repository ensures that [`pulschema`](https://github.com/cloudy-sky-software/pulschema) is able to consistently and predictably transform the resource provider's OpenAPI document to a Pulumi JSON schema document with little to no modifications required, except when conformance tests fail and changes at the source of the OpenAPI doc are not possible for any reason.
Generating a Pulumi JSON schema is the entrypoint to being able to generate Pulumi provider SDKs using [crosscode](https://www.pulumi.com/crosscode/).
## Conformance
- Ensure the OpenAPI doc is free of validation errors
- Ensure `operationId` is not empty for all endpoint paths/operations
- Well-designed REST API that follows a proper resource model
- https://www.thoughtworks.com/insights/blog/rest-api-design-resource-modeling
- https://restfulapi.net/resource-naming/
- Use `OneOf` schema with a discriminator instead of `AnyOf`
- Define enums as reusable schema refs instead of inline enums
- Mark read-only properties using the `readOnly` attribute
## Deciding Between GraphQL vs. REST API
Are you having discussions about whether or not your public API should be based on
GraphQL or REST? Then this is for you.
**tl;dr;** Choose REST API if you want to be able to generate SDKs for use with
infrastructure automation platforms. In some cases, you may want to have both.
Probably because your own client applications may use the GraphQL API. You might
be interested in describing your API spec using Microsoft's [TypeSpec](https://microsoft.github.io/typespec/)
which allows you to emit OpenAPI and GraphQL schema
docs from a single source.
The decision of whether or not you should choose GraphQL for any
number of reasons is out-of-scope for this document.
You'll have to do the due dilligence to see if it's the right fit for your
product. That said, GraphQL can be great for fields of applications that
are able to take advantage of the granularity in the request payload.
However, GraphQL lacks proper semantics that indicate the type of
action being performed. That is, in GraphQL, every non-query (read)
is simply a mutation. The only way to identify what _type_ of mutation
an operation is, is by looking at the name of the operation. There are
no standards for naming operations. While it's possible to solve that
by agreeing upon standard naming convention for operations, there is
still the problem of associating the mutations with each other.
That is, there is no way to know when a group of mutations
belong to a specific resource. By contrast, in a REST API,
all mutations for a resource can be easily identified by
the request URI path. REST by design operates at a
resource level. Hence, why it makes it perfect for
infrastructure automation platforms like Pulumi.