RESTful web services foundation

The NAS Bridge management API is based on RESTful web services. Representational State Transfer (REST) establishes a collection of guidelines and design principles for exposing server-based resources and managing their states. It uses mainstream standards, which provide a flexible and extensible foundation for managing the NAS Bridge.

Resources and state representation

The core aspects of the design 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. One of the first tasks in designing an application based on RESTful web services is to identify the resources.

  • Definition of resource states and associated state operations

    Resources are always in one of a finite number of states. The states and 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 clients and servers 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:

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

Every REST resource must be defined and made available using a well-defined addressing scheme. Uniform Resource Identifiers (URIs) are used to specify the endpoints where resources are located. URIs provide the general framework for creating unique names for resources that can be used in the network. 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 the design of 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 (and the one used in the NAS Bridge) 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: Once 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 both developers and non-developers to interact with the API in a user interface that illustrates how the API responds to parameters and options. The instructions provided 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 (Swagger) user interface are live operations. Be careful not to create, update, or delete configuration 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.