When creating an API poller, your first step is selecting one of the following methods for the request.
- GET sends a request for data from a URL.
- POST creates a new record.
The method you use for an API request depends on:
- What you want to do, and
- What rights you have.
Similar to how you need different rights to perform various tasks in most applications, you need rights to use different methods against an external API and get a successful response. For example, to use a GET request to retrieve data from the SolarWinds Platform SDK, no extra rights are required other than the SolarWinds Platform account credentials included in the parent request. However, to send a POST request that creates a new record, you typically require extra rights. For example, to use a POST request that adds a node to the SolarWinds Platform database, your SolarWinds Platform account must have Node Management rights.
GET retrieves data from an API
The most common method for API requests, GET, retrieves data from a specific endpoint within an API. If the request is successful, data is returned in a response payload. Most GET requests include some form of authorization in their headers; check the API documentation for details.
Here is an example of a GET request sent to the SolarWinds Platform API, asking for the names of three polling engines from a specific database table:
When this query is packaged with the rest of the data provided on the API Poller page, including authorization and headers, the entire request looks like the following:
GET https://localhost:17778/SolarWinds/InformationService/v3/Json/Query?query=SELECT+Uri+FROM+Orion.Pollers+ORDER+BY+PollerID+WITH+ROWS+1+TO+3+WITH+TOTALROWS HTTP/1.1
Authorization: Basic YWRtaW46
User-Agent: curl/7.20.0 (i386-pc-win32) libcurl/7.20.0 OpenSSL/0.9.8l zlib/1.2.3
POST sends data to an API to create or update a resource
Unlike the GET method that requests data from an external API, the POST method is used to send changes to an API endpoint. These requests typically include additional data in the message body, as opposed to GET request that may include all necessary details in the request URL.
POST requests usually require authentication by the external API. For example, you can use standard SolarWinds Platform account credentials to send GET requests that retrieve data from the SolarWinds Platform API (perhaps to retrieve a list of available nodes), but you need Node Management rights for the SolarWinds Platform to send a POST request (for example, to add a node), as defined on the Manage Accounts page.
POST requests supply additional data to the target in the message body, not the URL. Credentials, if configured for an API poller, are sent in a separate Header file.
Note the following details about API poller requests:
- Allow time for responses. The larger the data set, the longer the response time.
- Dedicated headers are required for pages that require logins.