Go API client for openapi

Introduction

Welcome to the OSHWA Open Source Hardware Certification API. We hope that you will use it to build on top of the OSHWA certification program. This documentation provides information on how to use the OSHWA REST API to view, create, and search OSHWA certified open source hardware projects. You can learn more about OSHWA here and more about OSHWA’s free open source hardware certification program here.

This API supports both read and write functions. You can use the read functions to pull information about certified hardware from the directory in order to explore and present it in new ways. We encourage you to use it to find new ways to understand and visualize the world of open source hardware!

You can use the write functions to make it easier to submit registration applications to the program. Originally, the only way to submit hardware for registration was through OSHWA’s application form. We hope that the write functionality will make it easier to integrate certification applications into existing workflows, and to connect platforms that already host open source hardware to the certification program.

If you have questions or comments about the API, please email us at info@oshwa.org. We would also love to know how you use the API! We encourage you to contact us at info@oshwa.org, or let us know on twitter at @OHSummit.

Tools

This API is documented in OpenAPI format. It is built with Swagger and ReDoc.

Using the API

In order to use the API, you must register for an API key. You can get your own API key here. If your token is not included or is invalid, the API will return an error. If you'd like to test the endpoints, check out our Swagger implementation, where you will be able to request a key, add the key to your requests, and explore OSHWA certified projects. You will also find code examples in this documentation.

Pagination

Project and Company results are returned in a wrapper object that contains total, limit, and offset values, which are useful for paginating over results.

{
  \"total\": 200, // Total number of matching items
  \"offset\": 0, // Number of items skipped in request
  \"limit\": 100, // Max number of items in request
  \"items\": [ {...} ] // List of items
}

The default limit for requests is 100, and the maximum limit is 1000. The default offset is 0. The above request returns the first 100 items. To get the next 100 items, the offset would be changed to 100. These parameters can be used to loop through the api and retrieve all items.

All items are returned in alphabetical order by projectName.

Authentication

All OSHWA API endpoints require Bearer Token Authentication. You can get an API key here.

Errors

The OSHWA API uses HTTP response status codes to indicate whether the response was successful. Detailed information about the response and how any errors might be resolved can be found in the body of the error message.

{
    \"error\": {
        \"statusCode\": 422,
        \"errorCode\": \"Unprocessable Entity\",
        \"message\": \"Validation Error: Input validation failed\",
        \"details\": [
            {
                \"msg\": \"Responsible Party Type is required\",
                \"param\": \"responsiblePartyType\",
                \"location\": \"body\"
            },
        ]
    }
}

Overview

This API client was generated by the OpenAPI Generator project. By using the OpenAPI-spec from a remote server, you can easily generate an API client.

• API version: 1.0.0
• Package version: 1.0.0
• Generator version: 7.13.0-SNAPSHOT
• Build package: org.openapitools.codegen.languages.GoClientCodegen For more information, please visit

Installation

Install the following dependencies:

go get github.com/stretchr/testify/assert
go get golang.org/x/net/context

Put the package under your project folder and add the following in import:

import openapi "github.com/pedalboard/oshwa-api"

To use a proxy, set the environment variable HTTP_PROXY:

os.Setenv("HTTP_PROXY", "http://proxy_name:proxy_port")

Configuration of Server URL

Default configuration comes with Servers field that contains server objects as defined in the OpenAPI specification.

Select Server Configuration

For using other server than the one defined on index 0 set context value openapi.ContextServerIndex of type int.

ctx := context.WithValue(context.Background(), openapi.ContextServerIndex, 1)

Templated Server URL

Templated server URL is formatted using default variables from configuration or from context value openapi.ContextServerVariables of type map[string]string.

ctx := context.WithValue(context.Background(), openapi.ContextServerVariables, map[string]string{
	"basePath": "v2",
})

Note, enum values are always validated and all unused variables are silently ignored.

URLs Configuration per Operation

Each operation can use different server URL defined using OperationServers map in the Configuration. An operation is uniquely identified by "{classname}Service.{nickname}" string. Similar rules for overriding default operation server index and variables applies by using openapi.ContextOperationServerIndices and openapi.ContextOperationServerVariables context maps.

ctx := context.WithValue(context.Background(), openapi.ContextOperationServerIndices, map[string]int{
	"{classname}Service.{nickname}": 2,
})
ctx = context.WithValue(context.Background(), openapi.ContextOperationServerVariables, map[string]map[string]string{
	"{classname}Service.{nickname}": {
		"port": "8443",
	},
})

Documentation for API Endpoints

All URIs are relative to https://certificationapi.oshwa.org

Class	Method	HTTP request	Description
CompanyAPI	ApiCompaniesNameGet	Get /api/companies/{name}	Search by company name
OptionsAPI	ApiOptionsGet	Get /api/options	Get a list of valid project values for country, responsibleParty, primaryType, additionalType, hardwareLicense,softwareLicense, and documentationLicense fields.
ProjectAPI	ApiProjectsGet	Get /api/projects	Get all OSHWA certified projects
ProjectAPI	ApiProjectsIdGet	Get /api/projects/{id}	Get an OSHWA certified project by ID.
ProjectAPI	ApiProjectsPost	Post /api/projects	Create a project for OSHWA certification
UserAPI	UsersSignupPost	Post /users/signup	Register as user and receive an api token to authorize API requests.

Documentation For Models

• ApiError
• ApiErrorError
• ApiErrorErrorDetailsInner
• ApiOptionsGet200Response
• ApiProjectsPost200Response
• Project
• ProjectCertificationMarkTerms
• ProjectCertificationMarkTermsAccurateContactInformation
• ProjectCertificationMarkTermsComplianceWithOfficialCertificationGuidelines
• ProjectCertificationMarkTermsOshwaCertificationMark
• ProjectCertificationMarkTermsResponsibility
• ProjectCertificationMarkTermsViolationsEnforcement
• ProjectCitationsInner
• PublicProject
• PublicProjects
• PublicProjectsItemsInner
• User
• UsersSignupPost201Response
• UsersSignupPostRequest

Documentation For Authorization

Authentication schemes defined for the API:

bearerAuth

• Type: HTTP Bearer token authentication

Example

auth := context.WithValue(context.Background(), openapi.ContextAccessToken, "BEARER_TOKEN_STRING")
r, err := client.Service.Operation(auth, args)

Documentation for Utility Methods

Due to the fact that model structure members are all pointers, this package contains a number of utility functions to easily obtain pointers to values of basic types. Each of these functions takes a value of the given basic type and returns a pointer to it:

• PtrBool
• PtrInt
• PtrInt32
• PtrInt64
• PtrFloat
• PtrFloat32
• PtrFloat64
• PtrString
• PtrTime

Author