Entrata API Request

This function sends an HTTP request to the Entrata API.

Use this function as a base template to create HTTP requests to the Entrata API. This function is used by other functions in this package to create requests to the Entrata API.

Usage

entrata(
  endpoint = NULL,
  method = NULL,
  method_version = "r1",
  method_params = list(NULL),
  ua = user_agent(),
  verbosity = NULL,
  perform = FALSE,
  extract = perform,
  enable_retry = FALSE,
  timeout = NULL,
  dry_run = FALSE,
  progress = FALSE,
  config = config::get("entrata"),
  ...
)

Arguments

endpoint

Entrata API Endpoint to send the request to. Default is NULL. See details for the available endpoints.

method

Entrata API Method to use in the request. Not to be confused with the HTTP request method (i.e. GET, POST), this method must be a method that is available in the Entrata API for the specified endpoint. The default value depends on whether the endpoint parameter was provided, if it is available the default value is the first method listed for that endpoint. If no endpoint is specified, NULL will be used as the method in the request body. See details for available methods by endpoint and more details on the structure of the request.

method_version

Entrata API Method Version to use in the request. Default is "r1". Some endpoints have multiple versions of the same method. The version should be provided as a string. See details for more information on the structure of the request and available versions by endpoint method.

method_params

List of parameters to use in the request body's "method" object. Default is an empty list. The parameters should be provided as a named list where the names are the parameter names and the values are the parameter values. See details for more information on the structure of the request and available parameters by endpoint method. The default value depends on whether the endpoint parameter was provided, if it is available the default value is an empty list. If no endpoint is specified, NULL will be used as the method in the request body.

ua

User Agent string to use in the request. Default is to use user_agent().

verbosity

How much information to print? This is a wrapper around req_verbose() that uses an integer to control verbosity:

0: no output
1: show headers
2: show headers and bodies
3: show headers, bodies, and curl status messages.

Use with_verbosity() to control the verbosity of requests that you can't affect directly.

perform

Logical value indicating whether to perform the request. Default is FALSE. If FALSE, the function will return the request object without performing the request. If TRUE, the function will perform the request and return the response object.

extract

Logical value indicating whether to extract the response. Default is the value of perform. If TRUE, the function will extract the response object and return it. If FALSE, the function will return the response object as is.

enable_retry

Logical value indicating whether to enable request retry. Default is FALSE. If TRUE, the function will enable request retry with the default retry settings. If FALSE, the function will not enable request retry.

timeout

Numeric value indicating the request timeout in seconds. Default is NULL. If provided, the function will set the request timeout to the provided value in seconds.

dry_run

Logical value indicating whether to perform a dry run of the request. Default is FALSE. If TRUE, the function will perform a dry run of the request before performing the actual request (or if perform is not set, will return the request object without performing the request).

progress

Logical value indicating whether to show progress of the request. Only useful for long running requests. Default is FALSE. If TRUE, the function will show the progress of the request.

config

Entrata API Configuration Values as a list. Default is to use config::get("entrata") to retrieve the configuration values from a config.yml configuration file. The configuration values should include the following keys: username, password, and base_url. See details.

...

Additional arguments to pass to the request object.

Value

httr2::request() object with the Entrata API request.

Details

This function creates a request to the Entrata API using the httr2 package.

Specifically, the function creates an HTTP POST request to the Entrata API by appending to the request's URL path the provided endpoint, assigning the POST HTTP Method, adding the necessary authentication, populating the necessary request headers, and deriving the request's body using the provided method name and params parameters. See below for details.

This is the raw format of the base template request:

where the Authorization header is a Basic authentication header with the provided username and password and the body is a JSON encoded data object using the provided method and params:

{
"data": {
  "auth": {
    "type": [
      "basic"
    ]
  },
  "requestId": [
    15
  ],
  "method": {
    "name": [
      "<method>"
    ],
    "version": [
      "r1"
    ],
    "params": {
      "param1": [
        "value1"
      ],
      "param2": [
        "value2"
      ]
    }
  }
}
}

Usage

Arguments

Value

Details

See also