{"id":24380599,"url":"https://github.com/cloudy-sky-software/cloud-provider-api-conformance","last_synced_at":"2025-12-29T01:22:49.650Z","repository":{"id":210892167,"uuid":"727693713","full_name":"cloudy-sky-software/cloud-provider-api-conformance","owner":"cloudy-sky-software","description":"A spec for cloud providers to make their REST APIs compatible for generating a native Pulumi provider.","archived":false,"fork":false,"pushed_at":"2024-09-30T06:00:41.000Z","size":15,"stargazers_count":4,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-01-19T08:32:27.022Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":null,"has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/cloudy-sky-software.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null}},"created_at":"2023-12-05T11:37:46.000Z","updated_at":"2024-09-30T06:00:45.000Z","dependencies_parsed_at":"2023-12-30T03:22:25.097Z","dependency_job_id":"bea5d100-f027-493a-84d7-0a8f94606ded","html_url":"https://github.com/cloudy-sky-software/cloud-provider-api-conformance","commit_stats":null,"previous_names":["cloudy-sky-software/cloud-provider-api-spec","cloudy-sky-software/cloud-provider-api-conformance"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cloudy-sky-software%2Fcloud-provider-api-conformance","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cloudy-sky-software%2Fcloud-provider-api-conformance/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cloudy-sky-software%2Fcloud-provider-api-conformance/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cloudy-sky-software%2Fcloud-provider-api-conformance/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/cloudy-sky-software","download_url":"https://codeload.github.com/cloudy-sky-software/cloud-provider-api-conformance/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243240781,"owners_count":20259469,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-01-19T08:27:31.709Z","updated_at":"2025-12-29T01:22:49.603Z","avatar_url":"https://github.com/cloudy-sky-software.png","language":null,"funding_links":[],"categories":[],"sub_categories":[],"readme":"# Pulumi Resource Provider API Conformance\n\n\u003e ⚠️ This document is actively evolving.\n\nThis 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.\n\nFollowing 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.\n\nGenerating a Pulumi JSON schema is the entrypoint to being able to generate Pulumi provider SDKs using [crosscode](https://www.pulumi.com/crosscode/).\n\n## Conformance\n\n- Ensure the OpenAPI doc is free of validation errors\n- Ensure `operationId` is not empty for all endpoint paths/operations\n- Well-designed REST API that follows a proper resource model\n  - https://www.thoughtworks.com/insights/blog/rest-api-design-resource-modeling\n  - https://restfulapi.net/resource-naming/\n- Use `OneOf` schema with a discriminator instead of `AnyOf`\n- Define enums as reusable schema refs instead of inline enums\n- Mark read-only properties using the `readOnly` attribute\n\n## Deciding Between GraphQL vs. REST API\n\nAre you having discussions about whether or not your public API should be based on\nGraphQL or REST? Then this is for you.\n\n**tl;dr;** Choose REST API if you want to be able to generate SDKs for use with\ninfrastructure automation platforms. In some cases, you may want to have both.\nProbably because your own client applications may use the GraphQL API. You might\nbe interested in describing your API spec using Microsoft's [TypeSpec](https://microsoft.github.io/typespec/)\nwhich allows you to emit OpenAPI and GraphQL schema\ndocs from a single source.\n\nThe decision of whether or not you should choose GraphQL for any\nnumber of reasons is out-of-scope for this document.\nYou'll have to do the due dilligence to see if it's the right fit for your\nproduct. That said, GraphQL can be great for fields of applications that\nare able to take advantage of the granularity in the request payload.\n\nHowever, GraphQL lacks proper semantics that indicate the type of\naction being performed. That is, in GraphQL, every non-query (read)\nis simply a mutation. The only way to identify what _type_ of mutation\nan operation is, is by looking at the name of the operation. There are\nno standards for naming operations. While it's possible to solve that\nby agreeing upon standard naming convention for operations, there is\nstill the problem of associating the mutations with each other.\nThat is, there is no way to know when a group of mutations\nbelong to a specific resource. By contrast, in a REST API,\nall mutations for a resource can be easily identified by\nthe request URI path. REST by design operates at a\nresource level. Hence, why it makes it perfect for\ninfrastructure automation platforms like Pulumi.\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcloudy-sky-software%2Fcloud-provider-api-conformance","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcloudy-sky-software%2Fcloud-provider-api-conformance","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcloudy-sky-software%2Fcloud-provider-api-conformance/lists"}