apiclient

package module
v0.3.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Feb 8, 2021 License: BSD-3-Clause Imports: 11 Imported by: 0

README

PoC OONI client API

This repository contains a PoC where we automatically generate Go clients for using the OONI API.

Most code is generated from annotated data structures and from definitions of all the supported APIs.

We generate a Swagger 2.0 definition of the API recognized by the client. Tests check whether the client's definition of the API is in sync with the server's own definition.

This code will eventually be merged into ooni/probe-cli.

Documentation

Overview

Package apiclient contains clients for the OONI API.

Usage

For each defined API Foobar, there is a structure called FoobarAPI. Instantiate a new FoobarAPI structure. In most cases, the zero structure is already valid. In some cases, you need to explicitly initialize the auth token.

You MAY reuse the same FoobarAPI structure to service multiple requests.

To call the API, create and fill a FoobarRequest structure. Pass this structure along with a valid context to FoobarAPI's Call method.

You will get back either an error (and a nil FoobarResponse instance) or a valid FoobarResponse instance (and a nil error).

Maintenance

Edit internal/datamodel to change the request and response structures. Edit internal/apimodel to change the API specification. Run 

go generate ./...

To regenerate all the definitions exported by this package.

API documentation

Please, refer to https://api.ooni.io/apidocs/ for more info.

Index

Examples

Constants

This section is empty.

Variables

View Source 
var (
	ErrHTTPFailure     = errors.New("apiclient: http request failed")
	ErrJSONLiteralNull = errors.New("apiclient: server returned us a literal null")
	ErrEmptyField      = errors.New("apiclient: empty field")
	ErrEmptyToken      = errors.New("apiclient: empty auth token")
)

Errors defined by this package. In addition to these errors, this package may of course return any other stdlib specific error.

Functions

func Swagger added in v0.2.0 

func Swagger() string

Swagger returns the API swagger v2.0 as a serialized JSON.

Types

type CheckInAPI added in v0.2.0 

type CheckInAPI struct {
	BaseURL    string
	HTTPClient *http.Client
	UserAgent  string
}

CheckInAPI is the CheckIn API. The zero-value structure works as intended using suitable default values.

func (CheckInAPI) Call added in v0.2.0 

func (api CheckInAPI) Call(ctx context.Context, in *CheckInRequest) (*CheckInResponse, error)

Call calls POST /api/v1/check-in. Arguments MUST NOT be nil. The return value is either a non-nil error or a non-nil result.

type CheckInRequest 

type CheckInRequest struct {
	Charging        bool                           `json:"charging"`
	OnWiFi          bool                           `json:"on_wifi"`
	Platform        string                         `json:"platform"`
	ProbeASN        string                         `json:"probe_asn"`
	ProbeCC         string                         `json:"probe_cc"`
	RunType         string                         `json:"run_type"`
	SoftwareName    string                         `json:"software_name"`
	SoftwareVersion string                         `json:"software_version"`
	WebConnectivity *CheckInRequestWebConnectivity `json:"web_connectivity"`
}

CheckInRequest is the check-in API request

type CheckInRequestWebConnectivity 

type CheckInRequestWebConnectivity struct {
	CategoryCodes []string `json:"category_codes"`
}

CheckInRequestWebConnectivity contains WebConnectivity specific parameters to include into CheckInRequest

type CheckInResponse 

type CheckInResponse struct {
	WebConnectivity *CheckInResponseWebConnectivity `json:"web_connectivity"`
}

CheckInResponse is the check-in API response

type CheckInResponseURLInfo 

type CheckInResponseURLInfo struct {
	CategoryCode string `json:"category_code"`
	CountryCode  string `json:"country_code"`
	URL          string `json:"url"`
}

CheckInResponseURLInfo contains information about an URL.

type CheckInResponseWebConnectivity 

type CheckInResponseWebConnectivity struct {
	ReportID string                   `json:"report_id"`
	URLs     []CheckInResponseURLInfo `json:"urls"`
}

CheckInResponseWebConnectivity contains WebConnectivity specific information of a CheckInResponse

type CheckReportIDAPI added in v0.2.0 

type CheckReportIDAPI struct {
	BaseURL    string
	HTTPClient *http.Client
	UserAgent  string
}

CheckReportIDAPI is the CheckReportID API. The zero-value structure works as intended using suitable default values.

func (CheckReportIDAPI) Call added in v0.2.0 

func (api CheckReportIDAPI) Call(ctx context.Context, in *CheckReportIDRequest) (*CheckReportIDResponse, error)

Call calls GET /api/_/check_report_id. Arguments MUST NOT be nil. The return value is either a non-nil error or a non-nil result.

type CheckReportIDRequest 

type CheckReportIDRequest struct {
	ReportID string `query:"report_id" required:"true"`
}

CheckReportIDRequest is the CheckReportID request.

type CheckReportIDResponse 

type CheckReportIDResponse struct {
	Found bool `json:"found"`
}

CheckReportIDResponse is the CheckReportID response.

type LoginAPI added in v0.2.0 

type LoginAPI struct {
	BaseURL    string
	HTTPClient *http.Client
	UserAgent  string
}

LoginAPI is the Login API. The zero-value structure works as intended using suitable default values.

func (LoginAPI) Call added in v0.2.0 

func (api LoginAPI) Call(ctx context.Context, in *LoginRequest) (*LoginResponse, error)

Call calls POST /api/v1/login. Arguments MUST NOT be nil. The return value is either a non-nil error or a non-nil result.

type LoginRequest 

type LoginRequest struct {
	ClientID string `json:"username"`
	Password string `json:"password"`
}

LoginRequest is the login API request

type LoginResponse 

type LoginResponse struct {
	Expire string `json:"expire"`
	Token  string `json:"token"`
}

LoginResponse is the login API response

type MeasurementMetaAPI added in v0.2.0 

type MeasurementMetaAPI struct {
	BaseURL    string
	HTTPClient *http.Client
	UserAgent  string
}

MeasurementMetaAPI is the MeasurementMeta API. The zero-value structure works as intended using suitable default values.

func (MeasurementMetaAPI) Call added in v0.2.0 

func (api MeasurementMetaAPI) Call(ctx context.Context, in *MeasurementMetaRequest) (*MeasurementMetaResponse, error)

Call calls GET /api/v1/measurement_meta. Arguments MUST NOT be nil. The return value is either a non-nil error or a non-nil result.

type MeasurementMetaRequest 

type MeasurementMetaRequest struct {
	ReportID string `query:"report_id" required:"true"`
	Full     bool   `query:"full"`
	Input    string `query:"input"`
}

MeasurementMetaRequest is the MeasurementMeta Request.

type MeasurementMetaResponse 

type MeasurementMetaResponse struct {
	Anomaly              bool   `json:"anomaly"`
	CategoryCode         string `json:"category_code"`
	Confirmed            bool   `json:"confirmed"`
	Failure              bool   `json:"failure"`
	Input                string `json:"input"`
	MeasurementStartTime string `json:"measurement_start_time"`
	ProbeASN             int64  `json:"probe_asn"`
	ProbeCC              string `json:"probe_cc"`
	RawMeasurement       string `json:"raw_measurement"`
	ReportID             string `json:"report_id"`
	Scores               string `json:"scores"`
	TestName             string `json:"test_name"`
	TestStartTime        string `json:"test_start_time"`
}

MeasurementMetaResponse is the MeasurementMeta Response.

type OpenReportAPI added in v0.2.0 

type OpenReportAPI struct {
	BaseURL    string
	HTTPClient *http.Client
	UserAgent  string
}

OpenReportAPI is the OpenReport API. The zero-value structure works as intended using suitable default values.

func (OpenReportAPI) Call added in v0.2.0 

func (api OpenReportAPI) Call(ctx context.Context, in *OpenReportRequest) (*OpenReportResponse, error)

Call calls POST /report. Arguments MUST NOT be nil. The return value is either a non-nil error or a non-nil result.

type OpenReportRequest 

type OpenReportRequest struct {
	DataFormatVersion string `json:"data_format_version"`
	Format            string `json:"format"`
	ProbeASN          string `json:"probe_asn"`
	ProbeCC           string `json:"probe_cc"`
	SoftwareName      string `json:"software_name"`
	SoftwareVersion   string `json:"software_version"`
	TestName          string `json:"test_name"`
	TestStartTime     string `json:"test_start_time"`
	TestVersion       string `json:"test_version"`
}

OpenReportRequest is the OpenReport request.

type OpenReportResponse 

type OpenReportResponse struct {
	ReportID         string   `json:"report_id"`
	SupportedFormats []string `json:"supported_formats"`
}

OpenReportResponse is the OpenReport response.

type PsiphonConfigAPI added in v0.2.0 

type PsiphonConfigAPI struct {
	BaseURL    string
	HTTPClient *http.Client
	Token      string
	UserAgent  string
}

PsiphonConfigAPI is the PsiphonConfig API. The zero-value structure is not valid because Token is always required. We use suitable defaults for any other zero-initialized field.

func (PsiphonConfigAPI) Call added in v0.2.0 

func (api PsiphonConfigAPI) Call(ctx context.Context, in *PsiphonConfigRequest) (PsiphonConfigResponse, error)

Call calls GET /api/v1/test-list/psiphon-config. Arguments MUST NOT be nil. The return value is either a non-nil error or a non-nil result.

type PsiphonConfigRequest 

type PsiphonConfigRequest struct{}

PsiphonConfigRequest is the request for the PsiphonConfig API

type PsiphonConfigResponse 

type PsiphonConfigResponse map[string]interface{}

PsiphonConfigResponse is the response from the PsiphonConfig API

type RegisterAPI added in v0.2.0 

type RegisterAPI struct {
	BaseURL    string
	HTTPClient *http.Client
	UserAgent  string
}

RegisterAPI is the Register API. The zero-value structure works as intended using suitable default values.

func (RegisterAPI) Call added in v0.2.0 

func (api RegisterAPI) Call(ctx context.Context, in *RegisterRequest) (*RegisterResponse, error)

Call calls POST /api/v1/register. Arguments MUST NOT be nil. The return value is either a non-nil error or a non-nil result.

type RegisterRequest 

type RegisterRequest struct {
	AvailableBandwidth string   `json:"available_bandwidth,omitempty"`
	DeviceToken        string   `json:"device_token,omitempty"`
	Language           string   `json:"language,omitempty"`
	NetworkType        string   `json:"network_type,omitempty"`
	Platform           string   `json:"platform"`
	ProbeASN           string   `json:"probe_asn"`
	ProbeCC            string   `json:"probe_cc"`
	ProbeFamily        string   `json:"probe_family,omitempty"`
	ProbeTimezone      string   `json:"probe_timezone,omitempty"`
	SoftwareName       string   `json:"software_name"`
	SoftwareVersion    string   `json:"software_version"`
	SupportedTests     []string `json:"supported_tests"`
}

RegisterRequest is the request for the Register API.

type RegisterResponse 

type RegisterResponse struct {
	ClientID string `json:"client_id"`
}

RegisterResponse is the response from the Register API.

type SubmitMeasurementAPI added in v0.2.0 

type SubmitMeasurementAPI struct {
	BaseURL    string
	HTTPClient *http.Client
	UserAgent  string
}

SubmitMeasurementAPI is the SubmitMeasurement API. The zero-value structure works as intended using suitable default values.

func (SubmitMeasurementAPI) Call added in v0.2.0 

func (api SubmitMeasurementAPI) Call(ctx context.Context, in *SubmitMeasurementRequest) (*SubmitMeasurementResponse, error)

Call calls POST /report/{{ .ReportID }}. Arguments MUST NOT be nil. The return value is either a non-nil error or a non-nil result.

type SubmitMeasurementRequest 

type SubmitMeasurementRequest struct {
	ReportID string      `path:"report_id"`
	Format   string      `json:"format"`
	Content  interface{} `json:"content"`
}

SubmitMeasurementRequest is the SubmitMeasurement request.

type SubmitMeasurementResponse 

type SubmitMeasurementResponse struct{}

SubmitMeasurementResponse is the SubmitMeasurement response.

type TestHelpersAPI added in v0.2.0 

type TestHelpersAPI struct {
	BaseURL    string
	HTTPClient *http.Client
	UserAgent  string
}

TestHelpersAPI is the TestHelpers API. The zero-value structure works as intended using suitable default values.

func (TestHelpersAPI) Call added in v0.2.0 

func (api TestHelpersAPI) Call(ctx context.Context, in *TestHelpersRequest) (TestHelpersResponse, error)

Call calls GET /api/v1/test-helpers. Arguments MUST NOT be nil. The return value is either a non-nil error or a non-nil result.

type TestHelpersHelperInfo 

type TestHelpersHelperInfo struct {
	Address string `json:"address"`
	Type    string `json:"type"`
	Front   string `json:"front,omitempty"`
}

TestHelpersHelperInfo is a single helper within the response returned by the TestHelpers API.

type TestHelpersRequest 

type TestHelpersRequest struct{}

TestHelpersRequest is the TestHelpers request.

type TestHelpersResponse 

type TestHelpersResponse map[string][]TestHelpersHelperInfo

TestHelpersResponse is the TestHelpers response.

type TorTargetsAPI added in v0.2.0 

type TorTargetsAPI struct {
	BaseURL    string
	HTTPClient *http.Client
	Token      string
	UserAgent  string
}

TorTargetsAPI is the TorTargets API. The zero-value structure is not valid because Token is always required. We use suitable defaults for any other zero-initialized field.

func (TorTargetsAPI) Call added in v0.2.0 

func (api TorTargetsAPI) Call(ctx context.Context, in *TorTargetsRequest) (TorTargetsResponse, error)

Call calls GET /api/v1/test-list/tor-targets. Arguments MUST NOT be nil. The return value is either a non-nil error or a non-nil result.

Example 
package main

import (
	"context"
	"fmt"
	"log"

	"github.com/bassosimone/apiclient"
)

func main() {
	api := apiclient.TorTargetsAPI{
		Token: "valid-token-here",
	}
	request := &apiclient.TorTargetsRequest{}
	ctx := context.Background()
	response, err := api.Call(ctx, request)
	if err != nil {
		log.Fatal(err)
	}
	fmt.Printf("%d", len(response))
}

Output:

type TorTargetsRequest 

type TorTargetsRequest struct{}

TorTargetsRequest is a request for the TorTargets API.

type TorTargetsResponse 

type TorTargetsResponse map[string]TorTargetsTarget

TorTargetsResponse is the response from the TorTargets API.

type TorTargetsTarget 

type TorTargetsTarget struct {
	Address  string              `json:"address"`
	Name     string              `json:"name"`
	Params   map[string][]string `json:"params"`
	Protocol string              `json:"protocol"`
	Source   string              `json:"source"`
}

TorTargetsTarget is a target for the tor experiment.

type URLsAPI added in v0.3.0 

type URLsAPI struct {
	BaseURL    string
	HTTPClient *http.Client
	UserAgent  string
}

URLsAPI is the URLs API. The zero-value structure works as intended using suitable default values.

func (URLsAPI) Call added in v0.3.0 

func (api URLsAPI) Call(ctx context.Context, in *URLsRequest) (*URLsResponse, error)

Call calls GET /api/v1/test-list/urls. Arguments MUST NOT be nil. The return value is either a non-nil error or a non-nil result.

Example 
package main

import (
	"context"
	"fmt"
	"log"

	"github.com/bassosimone/apiclient"
)

func main() {
	var api apiclient.URLsAPI
	request := &apiclient.URLsRequest{
		CountryCode: "IT",
		Limit:       14,
	}
	ctx := context.Background()
	response, err := api.Call(ctx, request)
	if err != nil {
		log.Fatal(err)
	}
	fmt.Printf("%+v", response)
}

Output:

type URLsRequest added in v0.3.0 

type URLsRequest struct {
	CategoryCodes string `query:"category_codes"`
	CountryCode   string `query:"country_code"`
	Limit         int64  `query:"limit"`
}

URLsRequest is the URLs request.

type URLsResponse added in v0.3.0 

type URLsResponse struct {
	Results []URLsResponseURL `json:"results"`
}

URLsResponse is the URLs response.

type URLsResponseURL added in v0.3.0 

type URLsResponseURL struct {
	CategoryCode string `json:"category_code"`
	CountryCode  string `json:"country_code"`
	URL          string `json:"url"`
}

URLsResponseURL is a single URL in the URLs response.

Source Files

View all Source files

Directories

Path Synopsis
internal
apimodel
Package apimodel describes all the implemented APIs.
 Package apimodel describes all the implemented APIs.
datamodel
Package datamodel describes the data types used by OONI's API.
 Package datamodel describes the data types used by OONI's API.
diffmodel
Command diffmodel compares our model and the server model.
 Command diffmodel compares our model and the server model.
fatalx
Package fatalx simplifies checking for errors.
 Package fatalx simplifies checking for errors.
fmtx
Package fmtx extends the fmt package
 Package fmtx extends the fmt package
gencall
Command gencall generates call.go.
 Command gencall generates call.go.
gendatamodel
Command gendatamodel generates datamodel.go.
 Command gendatamodel generates datamodel.go.
gennewrequest
Command gennewrequest generates newrequest.go.
 Command gennewrequest generates newrequest.go.
gennewresponse
Command gennewresponse generates newresponse.go.
 Command gennewresponse generates newresponse.go.
genswagger
Command genswagger generates swagger.go.
 Command genswagger generates swagger.go.
openapi
Package openapi contains data structures for Swagger v2.0.
 Package openapi contains data structures for Swagger v2.0.
osx
Package osx extends the os package.
 Package osx extends the os package.
reflectx
Package reflectx extends the reflect package.
 Package reflectx extends the reflect package.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.