Reading this Book

This chapter introduces the various features and assumptions of this book. It assumes you are reading an HTML version of this book, live on the server. The available options and formatting will differ for other formats, such as the print version or PDF.

This book is organized into chapters, each on a separate page. Chapters may be nested into a hierarchy, and each chapter is subdivided by headings.

Navigation

On the left is a sidebar which provides a list of all chapters. Click on the chapter title to move to a different page. If the sidebar is not present, it may be opened using the icon.

The and buttons at the sides of the page may be used to go to the Previous and Next page, respectively. The left and right arrow keys will also do the same.

Tools

At the top of the page is the title bar which provides several tools.

Clicking the title bar will return you to the top of the page.

Search

A search box may be opened by pressing the search icon () or by pressing the S key on the keyboard. Click the results, or use the up and down arrow keys and enter to open the highlighted result, to navigate to that section.

The search term will be highlighted in the page. Clicking on the highlighted search term or using the Esc key will clear the highlighting.

Code Blocks

Code blocks may contain several different icons for interacting with them:

The icons appear when hovering over the code block.

Examples

Examples are provided to demonstrate how to call API endpoints and the expected responses.

Requests

Example requests are written in the HTTP wire format and give important information about how to invoke the endpoints.

HTTP GET Request

A typical HTTP GET request looks like:

GET https://oauth.iracing.com/oauth2/some/endpoint?example=true&another=false HTTP/1.1
Authorization: Bearer ...elided...

Examining each piece in turn:

• GET

  This is an HTTP GET request, as opposed to POST or some other HTTP method. This is what a web browser does when naviating to a page. Parameters to the endpoint will appear at the end of the endpoint URL.

• https://oauth.iracing.com/oauth2/some/endpoint?example=true&another=false

  This is the endpoint URL. It starts with the Base URL and continues with the API endpoint and any parameters. In this case, the endpoint /some/endpoint followed by the parameters example with the value true and another with the value false.

• HTTP/1.1

  This is an implementation detail of the HTTP protocol, specifying its version. Most clients will allow for this to be omitted.

• Authorization: Bearer ...elided...

  Some requests will require an access token. If an access token is required, the example will have this text. This is an Authorization header with an authentication scheme of 'Bearer'. The full text of the access token should be used in place of ...elided... here.

HTTP POST Request

A typical HTTP POST request looks like:

POST /oauth2/other/endpoint HTTP/1.1
Host: oauth.iracing.com
Authorization: Bearer ...elided...
Content-Type: application/x-www-form-urlencoded

example=true&another=false

Examining each piece in turn:

• POST

  This is an HTTP POST request, as opposed to GET or some other HTTP method. Browsers typically do this when submitting a form, for example. Parameters to the endpoint are sent in the body of the request.

• /oauth2/other/endpoint

  This is the endpoint URL, which starts with the non-host part of the Base URL and continues with the API endpoint. In this case, this is /other/endpoint as it would be referenced in this book.

• HTTP/1.1

  This is an implementation detail of the HTTP protocol, specifying its version. Most clients will allow for this to be omitted.

• Host: oauth.iracing.com

  This is a header that designates the server which should handle the request. Most clients will take care of this automatically.

• Authorization: Bearer ...elided...

  Some requests will require an access token. If an access token is required, the example will have this text. This is an Authorization header with an authentication scheme of 'Bearer'. The full text of the access token should be used in place of ...elided... here.

• Content-Type: application/x-www-form-urlencoded

  A Content-Type header tells the developer what format the API is expecting for any data submitted in the POST body. The API uses the application/x-www-form-urlencoded for the POST body format whenever possible.

• example=true&another=false

  A blank line separates the last header from the POST body data. In this case, the data are the parameters example with the value true and another with the value false.

Responses

Responses are often simplified and not written in the full HTTP wire format.

JSON Responses

This API favors JSON response bodies whenever appropriate. The documentation will call these out as an application/json object and give an example of the structure with sample data:

{
  "example": true,
  "another": false
}

An HTTP status code of 200 can be assumed.

Status-Code Only Responses

When there is no relevant data to be returned in the body, this will be noted in the documentation along with the expected status code:

"It responds with no body. An HTTP status code of 200 indicates success."

HTTP Wire Format Responses

Occasionally, the documentation may call out the full HTTP wire format of a response:

HTTP/1.1 307 Temporary Redirect
Location: https://localhost/some/endpoint?example=true&another=false

Examining each piece in turn:

• HTTP/1.1

  This is an implementation detail of the HTTP protocol, specifying its version.

• 307

  The HTTP status code.

• Temporary Redirect

  The canonical name of the HTTP status code.

• Location:

  This is a Location header, instructing the browser to navigate to a new URL.

• https://localhost/some/endpoint?example=true&another=false

  This is the URL to which the browser should navigate. It starts with the URL and continues with any parameters. In this case, the endpoint https://localhost/some/endpoint followed by the parameters example with the value true and another with the value false.

Error Responses

Error responses may be in any of the above formats. See the Errors chapter for more information.