Integration Guides › BFC API Reference Guide › BFC API Overview

BFC API Overview

This section contains the following topics:

The current interface into the BFC application is a RESTful (Representational state transfer) web application which generically exposes object types and object instances henceforth referred to as component types and components. All component types and components are available using these RESTful interfaces. Having generic interfaces for all facets of the BFC means that there are only a few concepts to learn. However, for a public API these generic concepts require in-depth knowledge of the BFC model. This document describes new public APIs which reduce the model knowledge that is required to interact with the BFC.

The BFC APIs support encoding in JavaScript Object Notation (JSON).

You can interact with the BFC APIs in the following ways:

Work directly with the RESTful web interfaces.
Use callable python modules.

BFC RESTful Semantics

Calls through the BFC API follow the RESTful web development pattern:

HTTPS is the transport protocol between the client and server.
HTTP Verbs indicate what action to take.
URLs identify resources on which to perform actions.
HTTP status codes are used to indicate coarse grain results for the API calls.
Errors display in a driver_fault record.

HTTPS Protocol

The HTTPS protocol is used between the client and server. Using this protocol leverages the fact that most firewalls have been configured to allow this traffic through. Additionally, we rely on the protocol to provide security of the information being transmitted between the client and server.

HTTP Verbs

Verb	Description
GET	Used to retrieve information from a resource. No side effects result when a client makes this call.
PUT	Used to replace information for a resource. If you wanted to update the description of a grid, you would use this verb. This call is idempotent.
POST	Primarily used to create a resource. In certain instances, this verb is used to start an operation. When used in a create operation, a typical return code is 201 and the location header will contain the URL for the newly created resource.
DELETE	Used to delete a resource identified in the URL. This call is idempotent.
HEAD	Not currently supported.

URLs

Uniform resource locators (URLs) are used to identify resources to operate on. Examples are: grids, networks, users, CA AppLogic versions, and so on. In addition to the resource identifier, the URL contains an application specification prefix (e.g. BFC). The application prefix provides the ability to support multiple applications with multiple versions hosted on the same infrastructure.

A complete URL example:

In this example, the application is BFC, the resource collection is grids, and the name of a specific grid instance is govt_sales.

BFC/grids/govt_sales

Note that a client chooses an API version by virtue of session login. In the 1.0 release (CA AppLogic 3.5), there is a single API version.

HTTP Status Codes

The following common codes are returned from interactions with the BFC APIs.

Code	Description
200	Success.
201	Resource created.
202	Request accepted and is pending completion. Signifies an asynchronous return from a potentially long running action.
204	The URI provided in the request is no longer valid. Used when the request deletes the resource.
304	Resource has not been modified. This code is mainly used in client-side caching.
4XX	A client made an invalid request. For example, a request was received to execute an action not supported for the given resource type or does not apply to the resource instance state.
401	The client is not authorized for access to this resource (URL). Check the login information passed in the request.
403	Access to this resource is forbidden. The request accesses a private component.
404	The client requested a URL that does not resolve to a resource. For example, the resource could have been deleted or the identifier passed was incorrect.
409	The request could not be completed due to a conflict with the current state of the resource. Used in situations where it is expected that the user might be able to resolve the conflict and resubmit the request.
5XX	An error occurred related to a problem within the server. Report this error to CA Technical Support.

Codes within the 400 range represent errors made by the client. The caller should scrutinize their request for errors and could possibly make another attempt. A code within the 500 range indicates an error internal to the BFC. There is likely nothing the client can do to resolve it themself.

Errors

When a client receives a 400 or 5XX error from the BFC APIs, the resulting payload consists of a driver_fault record. The driver_fault record contains the following fields:

Field	Content	Notes
type	string() of either client \| driver \| dependency	Indicates if the error was caused by the client request, internal to the driver, or stemmed from a dependency (for which case additional information will be passed in the reason field, for example the nested driver_faults generated in the dependency).
subtype	string() of either missing \| conflict \| unexpected	Indicates that the call is trying an operation on a missing resource, causes a conflict within the BFC (for example creating or updating an entity which would create a duplicate), or is otherwise unexpected (the default). Used by the BFCAPI to aid in returning proper HTTP response codes. For example, a missing subtype generates a 404 HTTP status code whereas a conflict generates a 403 status code.
code	string() fully qualified <tenant>/<component_name>.<fault>.	For example: bbc/grid_service.fault_required_field, bbc/grid_service.fault_runtime_error.
fmt	string() with {integer()} to reference the arguments.	For example: "Invalid grid name {0}". The {0} is replaced by the first entry in the args field.
args	List containing [number()\|string()\|string()]	These combine (via replacement) with the fmt to create the error message.
path	[integer()]	This represents the path into the function argument list where the issue lies. If the error is with the second value of the third argument, the path would be [2,1]. Values start at 0, tuple arguments are treated as lists, records are treated as lists and exclude the first argument (the name of the record) in their paths.
function	string() name of the function (plus arity) being called.	For example: "createGrid/4". This example indicates that the createGrid function, which takes four arguments, was called.
dependency_id	integer()	The component id of the dependency component which created the fault. Passed when the driver_fault type = dependency indicating that the request is leveraging another component or external resource to fulfill the operation.
reason	[driver_fault()]	Contains any nested fault errors.
details	string()	Contains more detailed information on the error. For example, the stack trace.

Note: All fields contain the JSON value null when empty.