This section contains the following topics:
The BFC API supports encoding in JavaScript Object Notation (JSON).
The BFC APIs are grouped together using the application prefix 'BFC' in the URL. The application prefix will directly follow the host in the URL.
All of the APIs support versioning. API version numbers are relative to the API itself, not to the BFC. Thus, the API version need not change when the BFC version changes. An API version has two parts, major number and minor number. Multiple versions of the APIs can coexist at the same time. Procedures for discontinuing support for a version will be identified at a later time, but backward-compatibility will never be broken in a release where only the API number changes. Payload records may change between versions. The URL used to identify API versions will also identify the record version. The record itself will not contain a version number. However, some APIs may elect to include the version in the name of the record.
Initial availability of the BFC APIs will be in the 3.5.0 release of the BFC. The initial API version will be 1.0. A client requests an API version by establishing a session with an explicit version login URI. Every version of the BFC will support an explicit version login URI for each API version supported. No URIs other than login will contain explicit version numbers.
Example URLs for the initial release:
https://<bfchost>:8443/BFC/1.0/login https://<bfchost>:8443/BFC/...
If, hypothetically, a future release of the BFC contained a change to the grid APIs and wished to continue support for the 1.0 API, the following URLs might be supported in the new version:
https://<bfchost>:8443/BFC/1.0/login https://<bfchost>:8443/BFC/1.1/login https://<bfchost>:8443/BFC/grids/...
Note that the 1.1 version might also contain new APIs that did not exist in 1.0, in which case new URLs could be introduced:
https://<bfchost>:8443/BFC/servers/...
A client who logged in to the 1.0 URI would not have access to the new servers URI -- access attempts would return an HTTP 404 error.
All of the BFC APIs fall into one of three design patterns. Each type of entity being managed can have an administration interface for setting configuration data specific to the type. Each type can have a manager interface responsible for creating, reading, updating, and deleting (CRUD) the instances of the type. Finally, you can use operational interfaces to perform non-CRUD actions.
Types within the BFC API can have an optional administration interface for setting configuration data. The URL pattern is admin/<resource_type>s (for example, admin/grids).
This URL pattern is used when the configuration applies to all instances of the specified type. The administration pattern can also be applied to a resource instance when finer grained configuration is prescribed, for example, a specific grid. Scoping is accomplished by adding the ID of the targeted resource to the URL:
admin/<resource_type>/<resource_id>
For example:
admin/grids/mygrid
You can use a GET to return a record when the set of configuration data is fixed.
When an admin target has many configuration values, a dynamic list of configuration values is supported via the query string. This gives the client ultimate flexibility when deciding what pieces of data to pull from the server. The following is an example URL:
admin/grids?keys=backboneid,licensekey
To set configuration values, you use a PUT.
Additionally, administration interfaces allow setting specific configuration values using PUT to the URL with the key included (for example, admin/grids/backboneControllerId or /admin/discovery) and a payload for the updated value or values.
To clear a configuration value, use a PUT and the value null in the corresponding record. Optionally, you can use a DELETE with the key in the URL (for example, admin/grids/licensekey or admin/backboneId).
Example Target 1
BFC/admin/<resource_type>s, BFC/admin/<resource_type>/<resource_id>
Retrieve the configuration pertinent to the resource_type or resource.
Return: configuration record.
Replace the configuration.
Payload: sparse record containing the fields to be set.
Return: ok.
Result: Values in the sparse record are updated.
Example Target 2
BFC/admin/<resource_type>s/<parameter>, BFC/admin/<resource_type>/<resource_id>/<parameter>
Retrieve the configuration value for the named parameter.
Query String: N/A.
Return: configuration value.
Replace the configuration value.
Payload: new configuration value.
Return: ok.
Result: Value for the specified configuration parameter is updated.
Delete: the value for the specified configuration param.
Payload: N/A.
Return: ok.
Result: Value for the specified configuration parameter is unset.
Every resource type has a manager pattern interface. This interface is responsible for creating, reading, updating, and deleting (CRUD) instances of this type. The URL pattern is to make the resource type name plural. For example, grids or networks.
You use the POST action to create an instance of a type. The POST is to the manager URL and defines a payload for the resource type. For instance, to create a grid, POST to /grids with a payload consisting of the grid record.
You use the DELETE action to delete an instance of a resource type. The URL for the delete includes the unique identifier (ID, name, and so on) for the resource type. For example, DELETE /grids/govt_sales deletes the grid named govt_sales.
Instances of a resource type can be read using GET. This action returns a list containing the instances.
Updating an instance is done using a PUT to the url containing the instance identifier and a payload representing the changed attributes and resource type in a similar way described in the administration pattern above.
The manager pattern can also be applied to list attributes within a type where you do not want to specify the entire list in an update. For example, instead of using a PUT grids/admin with a payload containing the grid record with entire list of available grid ids filled in, use the manager pattern by issuing one of the CRUD calls to individual grid parameters using the following URL:
admin/grids/availableGridIds
This URL pattern can also be used to affect relationships of a type instance. For example, a POST to the servers attribute in a grid record will add the server (specified by the server record payload) to the grid, whereas a DELETE to the same will remove it.
Example Target 1
BFC/<resource_type>s
Retrieve the instances managed by this Manager.
Return: A list of resource records.
Create instance managed by the Manager.
Payload: resource record.
Return: Instance Name.
Result: Created instance is added to existing managed resources.
Example Target 2
BFC/<resource_type>s/<instance id>
Retrieve the instance identified by the URL.
Return: A single resource record.
Update: update the instance.
Payload: sparse record containing the attributes to be set.
Return: ok.
Result: Resource is updated.
Create a connection to, or sub-resource for the resource.
Payload: resource record (sparse, e.g. with id only, or fully populated sub-component definition).
Return: Instance identifier.
Result: Resource is connected to, or created for, the resource instance.
Delete the resource, or undo the relationship identified by the resource in the URL.
Payload: N/A.
Return: ok.
Result: Instance is removed from the existing managed resources or the resource relationship.
Operations which do not fit into the Create Read Update Delete (CRUD) manager pattern are handled by the Operations pattern. Operations range from changing the state of a resource to having a resource perform an operation such as resetting power passwords.
The operations pattern is implemented using a POST to a URL ending with operations/<operation name> with an optional payload. In the following example, you start the grid named govt_sales:
POST grids/govt_sales/operations/start
In RESTful parlance the operations pattern creates a new resource identified by the operation name.
The operations pattern can and often is combined with the admin and manager patterns. Operations on a managed collection follow the admin pattern. However, operations on a managed instance follow the manager pattern.
The table in the next section describes (in a generic way) the URI structure, HTTP Method use, payload and return structure for how a BFC client interacts with the API applications.
Target Example
Operations such as:
BFC/admin/<resource_type>s/operations/<operation_name>, BFC/<resource_type>s/operations/<operation_name>, BFC/admin/<resource_type>/<resource_id>/operations/<operation_name>
Invokes the operation without a payload. Operations invoked using this must not create side effects.
Return: Results of the operation.
Same as GET but this can have side effects.
Payload: variable - defined by the operation.
Return: Results of the operation.
|
Copyright © 2013 CA Technologies.
All rights reserved.
|
|