HTTP methods, authentication, and response codes

In general, your app will send HTTPS requests to the DMI API using GET and POST with bearer authentication.

Methods

Only two methods are used with REST and DMI:

  • GET
    GET is a simple read command: the client uses a GET to request that the server send the client a copy of the data identified by the URL. All parameters necessary to a GET command are contained in the URL.
    Use GET for all DMI REST requests with getApplications, getDataViews, getResolutions, getDimensions, and getMetrics.
  • POST
    A POST request updates the resource identified by the URL in the request. A POST request must include a body in which all parameters are provided.
    Use POST for all DMI REST requests with methods getDMIData, getDMIData2, and getDMIData3.

Parameters are case-sensitive.

Authentication

Various HTTP authentication schemes are available to you, but "bearer" (also known as "token") authentication over HTTPS (SSL) is best for developing, testing, and using apps that access data through the NAM API.

Bearer authentication uses security tokens called bearer tokens.

  • A "bearer" in this scheme is an entity (in practice, an application) that holds a valid security token.
  • A "token" is a string that the client sends in the Authorization header during login.

The Authorization header your app sends during login should look like this:
Authorization: Bearer <token>
where your app would replace <token> with the actual token string.

And you should get that public API token from NAM. See the API tokens screen for more on generating public API tokens.

Example bearer authentication

In this example, we use the Postman REST client (one of many such third-party clients available to download) to issue a getApplications request to retrieve a list of applications from a NAM Server. In real life, you would add such functionality to your own app, so it can use our REST API to get information from a NAM Server.

  1. In the NAM Console menu, select Security ► API tokens.
  2. Create or select a public API token and copy the token to the clipboard. You will need this value later.
  3. In Postman, create a request of the form http://address/rest/dmiquery/getApplications Postman example request but use the real IP address of the NAM Server.
  4. Set Authorization to No Auth. We take care of authorization in the next step.
  5. On the Headers tab, we want to create an Authorization header containing the token as a Bearer value.
    • Enter a Key called Authorization
    • Enter a Value of Bearer followed by a space and then the full public API token. Postman example request - bearer
  6. Click Send to send that request to the specified NAM Server.
  7. If the call is successful, you will get a response from the NAM Server such as: {"offset": 0,"resultsCount": 10,"count": 10,"results": [["CVENT","Central Analysis Server"],["AV","Transaction Trace View"],["GOMEZ","Synthetic Monitoring"],["UEM","RUM Browser"],["L2","Layer 2"],["AMD","AMD Statistics"],["ESM","Enterprise Synthetic Health"],["ADOD","Advanced diagnostics on demand"],["ALARMS","Tools"],["SYSTEMDIAG","Diagnostic"]]}.

Response codes

Some standard HTML response codes you may encounter when developing with REST and HTTP.

  • 200 OK
    This response code indicates that the request has succeeded.
  • 201 Created
    This response code indicates that a PUT or POST request was successful and a resource was created.
  • 400 Bad Request
    This response code indicates that the request was malformed. You will see this when the data you send with a POST or PUT request is invalid or is formatted incorrectly.
  • 401 Unauthorized
    This response code indicates that you need to perform authentication before accessing the resource. Make sure the user and password you are sending in the request header has been created on the target machine and is authorized to carry out the request.
  • 403 Forbidden
    The provided user/password combination is not authorized to access the resource requested.
  • 404 Not Found
    This response code generally indicates that the request pointed to a URL with no corresponding resource.
  • 405 Method Not Allowed
    This response code indicates that the HTTP method used is not supported for this resource.
  • 500 Internal Server Error
    This response code indicates a problem (probably on the server side) other than those described by the other response codes.