Package api implements a client API for working with digitalrebar/provision.
const APIPATH = "/api/v3"
APIPATH is the base path for all API endpoints that digitalrebar provision provides.
DecodeYaml is a helper function for dealing with user input -- when accepting input from the user, we want to treat both YAML and JSON as first-class citizens. The YAML library we use makes that easier by using the json struct tags for all marshalling and unmarshalling purposes.
Note that the REST API does not use YAML as a wire protocol, so this function should never be used to decode data coming from the provision service.
Unmarshal is a helper for decoding the body of a response from the server. It should be called in one of two ways:
The first is when you expect the response body to contain a blob of data that needs to be streamed somewhere. In that case, ref should be an io.Writer, and the Content-Type header will be ignored.
The second is when you expect the response body to contain a serialized object to be unmarshalled. In that case, the response's Content-Type will be used as a hint to decide how to unmarshall the recieved data into ref.
In either case, if there are any errors in the unmarshalling process or the response StatusCode indicates non-success, an error will be returned and you should not expect ref to contain vaild data.
Client wraps *http.Client to include our authentication routines and routines for handling some of the biolerplate CRUD operations against digitalrebar provision.
TokenSession creates a new api.Client that will use the passed-in Token for authentication. It should be used whenever the API is not acting on behalf of a user.
UserSession creates a new api.Client that can act on behalf of a user. It will perform a single request using basic authentication to get a token that expires 600 seconds from the time the session is crated, and every 300 seconds it will refresh that token.
UserSession does not currently attempt to cache tokens to persistent storage, although that may change in the future.
AllIndexes returns all the static indexes available for all object types on the server.
Authorize sets the Authorization header in the Request with the current bearer token. The rest of the helper methods call this, so you don't have to unless you are building your own http.Requests.
Close should be called whenever you no longer want to use this client connection. It will stop any token refresh routines running in the background, and force any API calls made to this client that would communicate with the server to return an error
CreateModel takes the passed-in model and creates an instance of it on the server. It will return an error if the passed-in model does not validate or if it already exists on the server.
DeleteBlob deletes a blob on the server at the location indicated by 'at'
DeleteModel deletes the model matching the passed-in prefix and key. It returns the object that was deleted.
DoJSON does a complete round-trip, unmarshalling the body returned from the server into val. It calls RequestJSON to build the request.
Events creates a new EventStream from the client.
ExistsModel tests to see if an object exists on the server following the same rules as GetModel
FillModel fills the passed-in model with new information retrieved from the server.
GetBlob fetches a binary blob from the server. You are responsible for copying the returned io.ReadCloser to a suitable location and closing it afterwards if it is not nil, otherwise the client will leak open HTTP connections.
GetModel returns an object if type prefix with the unique identifier key, if such an object exists. Key can be either the unique ket for an object, or any field on an object that has an index that enforces uniqueness.
Indexes returns all the static indexes available for a given type of object on the server.
Info returns some basic system information that was retrieved as part of the initial authentication.
ListBlobs lists the names of all the binary objects at 'at', using the indexing parameters suppied by params.
ListModels returns all of the objects matching the passed params. If no params are passed, all objects of the specified type are returned.
OneIndex tests to see if there is an index on the object type indicated by prefix for a specific parameter. If the returned Index is empty, there is no such Index.
PatchModel attempts to update the object matching the passed prefix and key on the server side with the passed-in JSON patch (as sepcified in https://tools.ietf.org/html/rfc6902). To ensure that conflicting changes are rejected, your patch should contain the appropriate test stanzas, which will allow the server to detect and reject conflicting changes from different sources.
PostBlob uploads the binary blob contained in the passed io.Reader to the location specified by at on the server. You are responsible for closing the passed io.Reader.
PutModel replaces the server-side object matching the passed-in object with the passed-in object. Note that PutModel does not allow the server to detect and reject conflicting changes from multiple sources.
Request builds a preauthorized http.Request.
RequestJSON builds an http.Request that has the Accept and Content-Type headers set to application/json
Token returns the current authentication token associated with the Client.
UrlFor is a helper function used to build URLs for the other client helper functions.
WaitFor waits for an item to match test. It subscribes to an EventStream that watches all update and save envents for the object in question, and returns a string indicating whether the match succeeded, failed, or timed out.
The API for this function is subject to refactoring and change, and should not be considered to be stable yet.
EventStream recieves events from the digitalrebar provider. You can read recieved events by reading from its Events channel.
Close closes down the EventStream. You should drain the Events until you read a RecievedEvent that has an empty E and a non-nil Err
Deregister directs the EventStream to unsubscribe from Events from the digitalrebar provisioner. It takes the same parameters as Register.
Register directs the EventStream to subscribe to Events from the digital rebar provisioner.
Event subscriptions consist of a string with the following format:
type is the object type that you want to listen for events about. * means to listen for events about all object types.
action is the action that caused the event to be created. * means to listen for all actions.
key is the unique identifier of the object to listen for. * means to listen for events from all objects
RecievedEvent contains an event recieved from the digitalrebar provision server along with any errors that occurred while recieving the event.