API Basics

Overview

The Playfix API is a HTTP REST interface.

If you are not familiar with REST APIs, this is a good introduction: A Beginner’s Guide to HTTP and REST

HTTP Verbs

It follows the standard convention of using HTTP verbs, such as:

• GET - to query and retrieve data

• POST - to create new resources

• PATCH - to update attributes on a resource

• DELETE - to delete a resource

Parameters

You can send parameters to the API in two ways:

• query parameters

• request body

The request body is JSON. Nested objects are allowed in the request body. Any nested parameter keys will be written as a dot-delimited hierarchy. For example, config.symbol would refer to the parameter with the value "RWT" in the following snippet:

{
  "config": {
    "symbol": "RWT"
  }
}

Headers

You can use headers to send metadata with a request. Some common headers you will see used by Playfix are:

• Authorization

The Authorization header is used to pass along your bearer token, which identifies you to the system. Most Playfix endpoints are secured from open access. You should always pass along your authorization to be safe. <TODO: cover how to get your auth token>

• Content-Type

The Content-Type header specifies the format of the request body. You should always send "application/json" for now. All the examples and documentation will assume JSON requests.

• Accept

The Accept header specifies the response formats you can accept. You should always send "application/json" for now. All the examples and documentation will assume JSON responses.

Status Codes

HTTP status codes are used to convey the success or failure of API calls. Success is represented by a 2xx code. Failure is represented by a 4xx code.

Tools for Exploring the API

If you wish to interactively experiment with the Playfix API, you can use our Swagger docs or an application designed to interact with HTTP-based APIs, such as Insomnia.

Using Programming Languages

Libraries for interacting with REST HTTP APIs are widely available in almost every language. This guide contains examples both in Curl, a command-line tool that operates close to the level of the HTTP protocol, and Python, a popular programming language that should give you a good idea of how to call the Playfix API via code. You can translate the Python code examples to your favorite language as an exercise. This is a good way to familiarize yourself with how to code your own applications.