api_access: Prolific API access

In prolific.api: A User-Friendly Interface for Accessing the Prolific API

Prolific API access

Description

This class provides functionalities for accessing the Prolific API. The core method for this purpose is access, which can be used to create, review, change, manage and delete studies on the Prolific platform.
The fields and methods are available as in RefClass or S4 objects (see examples).

Fields

accessors

(character):
The commands for accessing the API. The command for each type of access method can be altered using this field. The default is

     accessors = c(
        get    = "curl",
        post   = "curl -X POST",
        put    = "curl -X PUT",
        patch  = "curl -X PATCH",
        delete = "curl -X DELETE"
     )

Note: A value for each of the names (get, post, put, patch and delete) is required, as these represent the methods that can be used when accessing the API.

api_token

(character):
The Prolific API token.

entrypoint

(character):
The API's entrypoint URL.

Methods

access

Main method for accessing the Prolific API

Parameters

endpoint

(character):

The endpoint to access. If this is a vector, its elements are collapsed by '/'.

method

(character):

The method to use. One of get, post, place, patch and delete. The commands associated with each method are defined in the accessors field of the api_access object.

data

(json string, json file, list, prolific_study object or NULL)

The data to be transfered in the body of the API call. R-objects are converted to a json string using jsonlite:toJSON . NULL means that no data is transfered.

as_list

(logical):

Whether the return of the API call should be converted to a list or (if applicable) prolific_study object, rather than returned as the raw json string.

Return Value

A list or json string, depending on argument as_list.

Usage

     api_access$access(
          endpoint,
          method,
          data,
          as_list
     )

check_authorization

Check whether the API authorization works

Return Value

A logical value that indicates whether the API authorization works.

Usage

     api_access$check_authorization()

Examples

library(prolific.api)

# Create API access
prolific_api_access <- api_access(api_token = "<api_token>")

# View fields
## RefClass Methods
prolific_api_access$accessors
prolific_api_access$api_token
prolific_api_access$entrypoint

## S4 Methods
accessors(prolific_api_access)
api_token(prolific_api_access)
entrypoint(prolific_api_access)

# Change fields
# (this is usually only required for the api_token)
# replace <new_token> in the by the actual API token
# before running these lines
## Not run: 
## RefClass Method
prolific_api_access$api_token <- "<new_token>"
## S4 Method
api_token(prolific_api_access) <- "<new_token>"

## End(Not run)


# Note: For the following code to work,
# you have to replace <new_token> in the lines above by the actual API token
## Not run: 
# Check wheter Authorization is working
## RefClass Method
prolific_api_access$check_authorization()
## S4 Method
check_authorization(prolific_api_access)

# Obtain list of existing studies
## RefClass Method
list_of_studies <-
    prolific_api_access$access(
        endpoint = "studies",
        method = "get",
        as_list = TRUE
    )
## S4 Method
list_of_studies2 <-
    access(
        prolific_api_access,
        endpoint = "studies",
        method = "get",
        as_list = TRUE
    )

## End(Not run)

prolific.api documentation built on Aug. 25, 2023, 5:15 p.m.