RESTful web services foundation

The NAS Bridge management API is based on RESTful web services. Representational State Transfer (REST) establishes guidelines for exposing server-based resources. It provides a flexible and extensible foundation for managing the NAS Bridge.

Resources and state representation

The core aspects of RESTful web services include the following:

Identification of system or server-based resources
Every system uses and maintains resources. A resource can be a file, business information, a process, or an administrative entity.
Definition of resource states and associated state operations
Resources are always in one of a finite number of states. The operations used to change states must be clearly defined.

Messages are exchanged between the client and server to access and change the state of resources according to the CRUD (Create, Read, Update, and Delete) operations.

HTTP messages

Hypertext Transfer Protocol (HTTP) is a protocol used by web services to exchange messages about resources. During HTTP message exchanges, the HTTP verbs are mapped to the resources and their corresponding state management actions.

The NAS Bridge management API relies on a subset of HTTP and uses the following HTTP verbs:

GET
PUT
POST
PATCH
DELETE

HTTP is stateless. Therefore, to associate a set of related requests and responses under one identity, additional information must be added to the data flows, including HTTP headers or cookies. Also note that HTTP uses TCP port 80 by default.

URI endpoints

Uniform Resource Identifiers (URIs) are used to specify the endpoints where resources are located. URIs provide the general framework for creating unique resource names. The resources are exposed in a structure that is similar to a hierarchical directory.

A Uniform Resource Locator (URL) is a type of URI adapted primarily for the web and used in RESTful web services. A URL is used to identify a resource and to access a representation of the resource.

JSON formatting

While there are several possible ways that information can be transferred between a web client and server, the most popular option is JavaScript Object Notation (JSON). JSON is a standard for representing simple data structures, including objects and arrays, in plain text. JSON is used by the NAS Bridge RESTful web services to represent and transfer state information describing each resource.

Multiple access paths

You can access the NAS Bridge management API in a few different ways:

NAS Bridge native user interface: An indirect way to access the API is through the NAS Bridge native web user interface. When you use a browser to access the NAS Bridge through its management IP address, the initial page is displayed with administrative functions organized by category. The browser accesses the management API and reformats the data according to the user interface design. In other words, you interact with the NAS Bridge user interface, and the user interface makes the corresponding API calls.
API Docs (Swagger) web page: After you have used a browser to access the NAS Bridge through its management IP address, you can access the API Docs web page, powered by the Swagger open source platform. The API Docs page allows you to interact with the API through a user interface that illustrates how the API responds to parameters and options. The instructions for using the NAS Bridge management API contain examples that show the API Docs (Swagger) interface.
Attention: Any API operations you perform using the API Docs webpage are live operations. Be careful not to create, update, or delete configuration data or other data by mistake.
Custom program – You can access the management API using one of several different programming languages and tools, such as Python, Java, and cURL. A program, script, or tool that uses the API acts as a RESTful web services client. Using a programming language enables you to better understand the API as well as to automate the management and control of a NAS Bridge.

Uploading data

If you want to upload a file using the API, such as a NAS Bridge recovery package, you must perform a POST with the multi-part content type. Otherwise, the file will not upload.