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 ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Delete ¶
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 ¶
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.
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 }
type UnexpectedResponseCodeError ¶
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