Skip to content

About

Read, write and validate OpenCollection files in Go

Topics

Resources

Stars

0 stars

Watchers

1 watching

Forks

Repository files navigation

go-opencollection

Go library for reading, writing, validating, and building OpenCollection YAML files — the open specification for API collections.

Installation

go get github.com/robertjndw/go-opencollection

Quick start

// Read a collection from a file or directory
c, err := opencollection.Open("my-api.yml")

// Build a collection programmatically
c := opencollection.New("My API").
    Summary("Internal REST API").
    CollectionVersion("1.0.0").
    AddHttpRequest(
        opencollection.BuildHttpRequest("Get Users", "GET", "{{baseUrl}}/users").
            Header("Accept", "application/json").
            BearerAuth("{{token}}").
            Build(),
    ).
    Build()

// Validate against the OpenCollection schema
if err := opencollection.Validate(c); err != nil {
    log.Fatal(err)
}

// Write to disk
err = opencollection.Write("my-api.yml", c)

I/O

Function Description
Open(path) Read a collection from a file or an unbundled directory
ParseFile(path) Read a bundled YAML file
Parse(data) Unmarshal a YAML byte slice
Write(path, c) Write to a file or directory depending on c.Bundled
WriteFile(path, c) Always write a single bundled YAML file
Marshal(c) Serialize to YAML bytes
ReadDir(dir) Read an unbundled directory layout
WriteDir(dir, c) Write an unbundled directory layout

Bundled vs. unbundled

Set c.Bundled = true to write everything into a single YAML file.
Set c.Bundled = false (the default) to use a directory layout:

my-api/
  opencollection.yml       # collection root
  environments/
    production.yml
    staging.yml
  get-users.yml            # request items
  users/
    folder.yml             # folder metadata
    create-user.yml
    get-user-by-id.yml

Validation

err := opencollection.Validate(c)

Validate marshals the collection to its canonical YAML form, round-trips it through JSON, and validates it against the embedded OpenCollection JSON schema. Validation errors are returned as plain Go errors with a message describing the failing constraint.

Builders

All builders return *Builder for chaining and end with .Build().

Collection

c := opencollection.New("Petstore API").
    Summary("OpenAPI Petstore example").
    CollectionVersion("2.0.0").
    Author("Alice", "alice@example.com", "").
    Bundled(true).
    Docs("Full API documentation at https://petstore.example.com/docs").
    Extension("x-team", "platform").
    Environment(
        opencollection.NewEnvironment("Production").
            Color("#d32f2f").
            Var("baseUrl", "https://api.petstore.example.com").
            Secret("apiKey", "string").
            Build(),
    ).
    DefaultRequest(
        opencollection.NewRequestDefaults().
            Header("X-Client-Version", "1.0").
            BearerAuth("{{apiKey}}").
            Build(),
    ).
    AddHttpRequest(req).
    AddFolder(folder).
    Build()

HTTP request

req := opencollection.BuildHttpRequest("Create Pet", "POST", "{{baseUrl}}/pets").
    Description("Creates a new pet in the store").
    Tag("pets").
    Header("Content-Type", "application/json").
    Header("Accept", "application/json").
    QueryParam("dryRun", "false").
    JSONBody(`{"name":"{{petName}}","status":"available"}`).
    BearerAuth("{{token}}").
    Var("petName", "Fido").
    BeforeRequest(`pm.request.headers.add({ key: "X-Request-ID", value: uuid() })`).
    Tests(`pm.test("status is 201", () => pm.response.to.have.status(201))`).
    Assert("response.status", "==", "201").
    Build()

Available body helpers: JSONBody, TextBody, XMLBody, FormBody.
Available auth helpers: BearerAuth, BasicAuth, InheritAuth, Auth(auth).
Available script helpers: BeforeRequest, AfterResponse, Tests, Script(type, code).

GraphQL request

gql := opencollection.BuildGraphQLRequest("List Pets", "https://api.example.com/graphql").
    Header("Accept", "application/json").
    Query(`query ListPets($limit: Int) { pets(limit: $limit) { id name } }`, `{"limit":10}`).
    BearerAuth("{{token}}").
    Assert("response.status", "==", "200").
    Build()

gRPC request

grpc := opencollection.BuildGrpcRequest("Get Pet", "grpc.petstore.example.com:443", "PetService/GetPet").
    MethodType("unary").
    ProtoFile("./proto/petstore.proto").
    Metadata("authorization", "Bearer {{token}}").
    Message(`{"id":"{{petId}}"}`).
    Build()

Method types: "unary", "client-streaming", "server-streaming", "bidi-streaming".

Folder

folder := opencollection.NewFolder("Pets").
    Description("Pet management endpoints").
    Seq(1).
    Tag("pets").
    DefaultRequest(
        opencollection.NewRequestDefaults().
            Header("X-Namespace", "pets").
            Build(),
    ).
    AddHttpRequest(req).
    AddFolder(nestedFolder).
    Build()

Environment

env := opencollection.NewEnvironment("Staging").
    Color("#f57c00").
    Extends("Production").
    DotEnvFile(".env.staging").
    Var("baseUrl", "https://staging.petstore.example.com").
    Secret("apiKey", "string").
    Build()

Request defaults

defaults := opencollection.NewRequestDefaults().
    Header("X-Client", "go-sdk").
    BearerAuth("{{token}}").
    Var("retries", "3").
    Script("before-request", `console.log("sending", pm.request.url)`).
    Build()

Auth

Standalone auth constructors can be passed anywhere an Auth is accepted:

opencollection.BearerAuth("{{token}}")
opencollection.BasicAuth("user", "pass")
opencollection.APIKeyAuth("X-API-Key", "{{apiKey}}", "header") // placement: "header" or "query"
opencollection.InheritAuth()  // inherit from parent scope

OAuth 2.0 is configured directly on the Auth struct:

auth := opencollection.Auth{
    IsSet: true,
    OAuth2: &opencollection.AuthOAuth2{
        ClientCredentials: &opencollection.OAuth2ClientCredentialsFlow{
            Type:           "oauth2",
            Flow:           "client_credentials",
            AccessTokenURL: "https://auth.example.com/token",
            Credentials: &opencollection.OAuth2ClientCredentials{
                ClientID:     "{{clientId}}",
                ClientSecret: "{{clientSecret}}",
            },
            Scope: "read:pets write:pets",
        },
    },
}

Data types

Description

Can be a plain string, a typed content+MIME object, or null:

opencollection.StringDescription("plain text")

opencollection.Description{
    IsSet:    true,
    Content:  "# Heading\nmarkdown body",
    MIMEType: "text/markdown",
}

opencollection.Description{IsSet: true, IsNull: true}

InheritableBool / InheritableInt

Fields on HttpRequestSettings (e.g. FollowRedirects, Timeout) can hold a concrete value or "inherit":

settings := opencollection.HttpRequestSettings{
    FollowRedirects: opencollection.InheritableBool{Set: true, Value: true},
    Timeout:         opencollection.InheritableInt{Set: true, Inherit: true},
}

VariableValue

A variable value can be a simple string, a typed {type, data} object, or a list of named variants:

// simple
opencollection.VariableValue{Simple: "hello"}

// typed
opencollection.VariableValue{Typed: &opencollection.TypedVariableValue{Type: "number", Data: "42"}}

// variants
opencollection.VariableValue{Variants: []opencollection.VariableValueVariant{
    {Title: "US East", Value: opencollection.VariableValue{Simple: "us-east-1"}},
    {Title: "EU West", Selected: true, Value: opencollection.VariableValue{Simple: "eu-west-1"}},
}}

Examples

See the examples/ directory for complete, runnable programs:

Example Description
build_and_write Build a collection with HTTP, GraphQL, gRPC items and write it to disk
read_and_inspect Open a collection file and iterate over its items
validate Parse a collection file and validate it against the schema
environments Add multiple environments with plain and secret variables
unbundled_dir Write and read back an unbundled directory layout

About

Read, write and validate OpenCollection files in Go

Topics

Resources

Stars

0 stars

Watchers

1 watching

Forks

Releases

Packages

Contributors

Languages