perigee

README

perigee

Perigee provides a REST client that, while it should be generic enough to use with most any RESTful API, is nonetheless optimized to the needs of the OpenStack APIs. Perigee grew out of the need to refactor out common API access code from the gorax project.

Several things influenced the name of the project. Numerous elements of the OpenStack ecosystem are named after astronomical artifacts. Additionally, perigee occurs when two orbiting bodies are closest to each other. Perigee seemed appropriate for something aiming to bring OpenStack and other RESTful services closer to the end-user.

This library is still in the very early stages of development. Unless you want to contribute, it probably isn't what you want

Installation and Testing

To install:

go get github.com/racker/perigee

To run unit tests:

go test github.com/racker/perigee

Contributing

The following guidelines are preliminary, as this project is just starting out. However, this should serve as a working first-draft.

Branching

The master branch must always be a valid build. The go get command will not work otherwise. Therefore, development must occur on a different branch.

When creating a feature branch, do so off the master branch:

git checkout master
git pull
git checkout -b featureBranch
git checkout -b featureBranch-wip   # optional

Perform all your editing and testing in the WIP-branch. Feel free to make as many commits as you see fit. You may even open "WIP" pull requests from your feature branch to seek feedback. WIP pull requests will never be merged, however.

To get code merged, you'll need to "squash" your changes into one or more clean commits in the feature branch. These steps should be followed:

git checkout featureBranch
git merge --squash featureBranch-wip
git commit -a
git push origin featureBranch

You may now open a nice, clean, self-contained pull request from featureBranch to master.

The git commit -a command above will open a text editor so that you may provide a comprehensive description of the changes.

In general, when submitting a pull request against master, be sure to answer the following questions:

• What is the problem?
• Why is it a problem?
• What is your solution?
• How does your solution work? (Recommended for non-trivial changes.)
• Why should we use your solution over someone elses? (Recommended especially if multiple solutions being discussed.)

Remember that monster-sized pull requests are a bear to code-review, so having helpful commit logs are an absolute must to review changes as quickly as possible.

Finally, (s)he who breaks master is ultimately responsible for fixing master.

Source Representation

The Go community firmly believes in a consistent representation for all Go source code. We do too. Make sure all source code is passed through "go fmt" before you create your pull request.

Please note, however, that we fully acknowledge and recognize that we no longer rely upon punch-cards for representing source files. Therefore, no 80-column limit exists. However, if a line exceeds 132 columns, you may want to consider splitting the line.

Unit and Integration Tests

Pull requests that include non-trivial code changes without accompanying unit tests will be flatly rejected. While we have no way of enforcing this practice, you can ensure your code is thoroughly tested by always writing tests first by intention.

When creating a pull request, if even one test fails, the PR will be rejected. Make sure all unit tests pass. Make sure all integration tests pass.

Documentation

Private functions and methods which are obvious to anyone unfamiliar with gorax needn't be accompanied by documentation. However, this is a code-smell; if submitting a PR, expect to justify your decision.

Public functions, regardless of how obvious, must have accompanying godoc-style documentation. This is not to suggest you should provide a tome for each function, however. Sometimes a link to more information is more appropriate, provided the link is stable, reliable, and pertinent.

Changing documentation often results in bizarre diffs in pull requests, due to text often spanning multiple lines. To work around this, put one logical thought or sentence on a single line. While this looks weird in a plain-text editor, remember that both godoc and HTML viewers will reflow text. The source code and its comments should be easy to edit with minimal diff pollution. Let software dedicated to presenting the documentation to human readers deal with its presentation.

Examples

t.b.d.

Documentation

Index

• func Delete(url string, opts Options) error
• func Get(url string, opts Options) error
• func Post(url string, opts Options) error
• func Put(url string, opts Options) error
• type Options
• type Response
  • func Request(method string, url string, opts Options) (*Response, error)
• type UnexpectedResponseCodeError
  • func (err *UnexpectedResponseCodeError) Error() string

Functions

func Delete

func Delete(url string, opts Options) error

Delete makes a DELETE request against a server using the provided HTTP client. The url must be a fully-formed URL string. DEPRECATED. Use Request() instead.

func Get

func Get(url string, opts Options) error

Get makes a GET request against a server using the provided HTTP client. The url must be a fully-formed URL string. DEPRECATED. Use Request() instead.

func Post

func Post(url string, opts Options) error

Post makes a POST request against a server using the provided HTTP client. The url must be a fully-formed URL string. DEPRECATED. Use Request() instead.

func Put

func Put(url string, opts Options) error

Put makes a PUT request against a server using the provided HTTP client. The url must be a fully-formed URL string. DEPRECATED. Use Request() instead.

Types

type Options

type Options struct {
	CustomClient  *http.Client
	ReqBody       interface{}
	Results       interface{}
	MoreHeaders   map[string]string
	OkCodes       []int
	StatusCode    *int    `DEPRECATED`
	DumpReqJson   bool    `UNSUPPORTED`
	ResponseJson  *[]byte `DEPRECATED`
	Response      **Response
	ContentType   string `json:"Content-Type,omitempty"`
	ContentLength int64  `json:"Content-Length,omitempty"`
	Accept        string `json:"Accept,omitempty"`
	SetHeaders    func(r *http.Request) error
}

Options describes a set of optional parameters to the various request calls.

The custom client can be used for a variety of purposes beyond selecting encrypted versus unencrypted channels. Transports can be defined to provide augmented logging, header manipulation, et. al.

If the ReqBody field is provided, it will be embedded as a JSON object. Otherwise, provide nil.

If JSON output is to be expected from the response, provide either a pointer to the container structure in Results, or a pointer to a nil-initialized pointer variable. The latter method will cause the unmarshaller to allocate the container type for you. If no response is expected, provide a nil Results value.

The MoreHeaders map, if non-nil or empty, provides a set of headers to add to those already present in the request. At present, only Accepted and Content-Type are set by default.

OkCodes provides a set of acceptable, positive responses.

If provided, StatusCode specifies a pointer to an integer, which will receive the returned HTTP status code, successful or not. DEPRECATED; use the Response.StatusCode field instead for new software.

ResponseJson, if specified, provides a means for returning the raw JSON. This is most useful for diagnostics. DEPRECATED; use the Response.JsonResult field instead for new software.

DumpReqJson, if set to true, will cause the request to appear to stdout for debugging purposes. This attribute may be removed at any time in the future; DO NOT use this attribute in production software.

Response, if set, provides a way to communicate the complete set of HTTP response, raw JSON, status code, and other useful attributes back to the caller. Note that the Request() method returns a Response structure as part of its public interface; you don't need to set the Response field here to use this structure. The Response field exists primarily for legacy or deprecated functions.

SetHeaders allows the caller to provide code to set any custom headers programmatically. Typically, this facility can invoke, e.g., SetBasicAuth() on the request to easily set up authentication. Any error generated will terminate the request and will propegate back to the caller.

type Response

type Response struct {
	HttpResponse http.Response
	JsonResult   []byte
	Results      interface{}
	StatusCode   int
}

func Request

func Request(method string, url string, opts Options) (*Response, error)

Request issues an HTTP request, marshaling parameters, and unmarshaling results, as configured in the provided Options parameter. The Response structure returned, if any, will include accumulated results recovered from the HTTP server. See the Response structure for more details.

type UnexpectedResponseCodeError

type UnexpectedResponseCodeError struct {
	Url      string
	Expected []int
	Actual   int
	Body     []byte
}

The UnexpectedResponseCodeError structure represents a mismatch in understanding between server and client in terms of response codes. Most often, this is due to an actual error condition (e.g., getting a 404 for a resource when you expect a 200). However, it needn't always be the case (e.g., getting a 204 (No Content) response back when a 200 is expected).

func (*UnexpectedResponseCodeError) Error

func (err *UnexpectedResponseCodeError) Error() string