RESTful web services foundation

The NAS Bridge management API is implemented based on RESTful web services technology. Representational State Transfer (REST) establishes a collection of technologies 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 node.

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 must be clearly defined, as must be the operations used to affect the state changes.

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

HTTP messages

Hypertext Transfer Protocol (HTTP) is the specific protocol used by the web services client and server to exchange request and response messages about the resources. During the RESTful web services design, the HTTP verbs are mapped to the resources and the corresponding state management actions.

The NAS Bridge management API relies on a subset of the HTTP protocol 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, and therefore a RESTful web services API, uses TCP port 80 by default.

URI endpoints

Every REST resource must be defined and made available using a well-defined addressing scheme. The endpoints where the resources are located and identified using a Uniform Resource Identifier (URI). The URI provides the general framework for creating the unique name of a resource that can be used in the network. The resources are exposed in a structure that is similar to a hierarchical directory.

The 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 the client and server, the most popular option (and the one used with 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 RESTful web services to represent and transfer state information describing each resource.

Multiple access paths

Because of the inherent flexibility of RESTful web services, the management API can be accessed in several different ways:
  • NAS Bridge native user interface – The primary way you access the API is through the NAS Bridge native web user interface. When you use a browser to access a node’s 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 design of the user interface.
  • Swagger web page – The NAS Bridge management API uses the Swagger open source API platform to provide an alternative access point to a NAS Bridge node when using a browser. Swagger 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.
    Attention: Any API operations you perform using the 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. Popular choices include 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 possibly automate the management and control of a NAS Bridge node.

Uploading data

When uploading files such as exported configuration files using the API, you must perform a POST with the multipart content type. Otherwise the file will fail to be uploaded.