api

Documentation

Overview

Package api defines the JSON-RPC API between the browser and the server as well as between mobile devices and the server.

Index

• Constants
• type CSRFResponse
• type ErrorReturn
  • func Error(err error) *ErrorReturn
  • func Errorf(msg string, vars ...interface{}) *ErrorReturn
  • func InternalError() *ErrorReturn
  • func (e *ErrorReturn) WithCode(code string) *ErrorReturn
• type IssueCodeRequest
• type IssueCodeResponse
• type VerificationCertificateRequest
• type VerificationCertificateResponse
• type VerifyCodeRequest
• type VerifyCodeResponse

Constants

const (
	// TestTypeConfirmed is the string that represents a confirmed covid-19 test.
	TestTypeConfirmed = "confirmed"
	// TestTypeLikely is the string that represents a clinical diagnosis.
	TestTypeLikely = "likely"
	// TestTypeNegative is the string that represents a negative test.
	TestTypeNegative = "negative"

	// error_code definitions for the APIs.
	// General
	ErrUnparsableRequest = "unparsable_request"
	ErrInternal          = "internal_server_error"

	// Verify API responses
	// ErrVerifyCodeInvalid indicates the code entered is unknown or already used.
	ErrVerifyCodeInvalid = "code_invalid"
	// ErrVerifyCodeExpired indicates the code provided is known to the server, but expired.
	ErrVerifyCodeExpired = "code_expired"

	// Certificate API responses
	// ErrTokenInvalid indicates the token provided is unknown or already used
	ErrTokenInvalid = "token_invalid"
	// ErrTokenExpired indicates that the token provided is known but expired.
	ErrTokenExpired = "token_expired"
	// ErrHMACInvalid indicates that the HMAC that is being signed is invalid (wrong length)
	ErrHMACInvalid = "hmac_invalid"
)

Types

type CSRFResponse

type CSRFResponse struct {
	CSRFToken string `json:"csrftoken"`
	Error     string `json:"error"`
	ErrorCode string `json:"errorCode"`
}

CSRFResponse is the return type when requesting an AJAX CSRF token.

type ErrorReturn

type ErrorReturn struct {
	Error     string `json:"error"`
	ErrorCode string `json:"error_code"`
}

ErrorReturn defines the common error type.

func Error

func Error(err error) *ErrorReturn

Error wraps the error into an API error.

func Errorf

func Errorf(msg string, vars ...interface{}) *ErrorReturn

Errorf creates an ErrorReturn w/ the formateed message.

func InternalError

func InternalError() *ErrorReturn

InternalError constructs a generic internal error.

func (*ErrorReturn) WithCode

func (e *ErrorReturn) WithCode(code string) *ErrorReturn

WithCode adds an error code to an ErrorReturn

type IssueCodeRequest

type IssueCodeRequest struct {
	TestType    string `json:"testType"`
	SymptomDate string `json:"symptomDate"` // ISO 8601 formatted date, YYYY-MM-DD
	Phone       string `json:"phone"`
}

IssueCodeRequest defines the parameters to request an new OTP (short term) code. This is called by the Web frontend. API is served at /api/issue

type IssueCodeResponse

type IssueCodeResponse struct {
	ID                 string `json:"id"` // Handle which allows the issuer to track status of the issued verification code.
	VerificationCode   string `json:"code"`
	ExpiresAt          string `json:"expiresAt"`          // RFC1123 string formatted timestamp, in UTC.
	ExpiresAtTimestamp int64  `json:"expiresAtTimestamp"` // Unix, seconds since the epoch. Still UTC.
	Error              string `json:"error"`
	ErrorCode          string `json:"errorCode,omitempty"`
}

IssueCodeResponse defines the response type for IssueCodeRequest.

type VerificationCertificateRequest

type VerificationCertificateRequest struct {
	VerificationToken string `json:"token"`
	ExposureKeyHMAC   string `json:"ekeyhmac"`
}

VerificationCertificateRequest is used to accept a long term token and an HMAC of the TEKs. The details of the HMAC calculation are available at: https://github.com/google/exposure-notifications-server/blob/main/docs/design/verification_protocol.md

Requires API key in a HTTP header, X-API-Key: APIKEY

type VerificationCertificateResponse

type VerificationCertificateResponse struct {
	Certificate string `json:"certificate,omitempty"`
	Error       string `json:"error,omitempty"`
	ErrorCode   string `json:"errorCode,omitempty"`
}

VerificationCertificateResponse either contains an error or contains a signed certificate that can be presented to the configured exposure notifications server to publish keys along w/ the certified diagnosis.

type VerifyCodeRequest

type VerifyCodeRequest struct {
	VerificationCode string `json:"code"`
}

VerifyCodeRequest is the request structure for exchanging a short term Verification Code (OTP) for a long term token (a JWT) that can later be used to sign TEKs.

Requires API key in a HTTP header, X-API-Key: APIKEY

type VerifyCodeResponse

type VerifyCodeResponse struct {
	TestType          string `json:"testtype,omitempty"`
	SymptomDate       string `json:"symptomDate,omitempty"` // ISO 8601 formatted date, YYYY-MM-DD
	VerificationToken string `json:"token,omitempty"`       // JWT - signed, not encrypted.
	Error             string `json:"error,omitempty"`
	ErrorCode         string `json:"errorCode,omitempty"`
}

VerifyCodeResponse either contains an error, or contains the test parameters (type and [optional] date) as well as the verification token. The verification token may be sent back on a valid VerificationCertificateRequest later.