How to use the CollyBird API

1. Introduction
2. HTTP
3. Host URL
4. Access tokens
5. Call a REST API method
6. HTTP methods
7. Tools for interacting with the CollyBird API
8. Example - get an access token
9. Example - list Roshambo matches
10. Example - create a Roshambo match

Introduction

The CollyBird API is the primary way to read and write to the CollyBird system. It's an HTTP-based API that apps can use to programmatically create, replace, update and delete with resources in the system.

HTTP

All data transfers conform to HTTP/1.1, and all endpoints require HTTPS. Because the Graph API is HTTP-based, it works with any language that has an HTTP library, such as cURL and urllib. This means you can use the Graph API directly in your browser. For example, requesting this URL in your browser...

https://www.collybird.com/api/roshambo

... is equivalent to performing this cURL request:

    curl 'http://localhost/api/roshambo' \
        -H 'Accept: application\json' \
        -H 'Authorization: Bearer 42|K...y'
    

Host URL

All requests are passed to the www.collybird.com host URL.

Access tokens

Access tokens allow your app to access the Roshambo API. Almost all Roshambo API endpoints require an access token of some kind, so each time you access an endpoint, your request may require one. They typically perform two functions:

• They allow your app to access a User's information without requiring the User's password. For example, your app needs a listing of the User's past matches to perform a function. If the User agrees to allow your app to retrieve their past matches from CollyBird, the User will not need to enter their CollyBird password for your app to get their past games.
• They allow us to identify your app, the User who is using your app, and the type of data the User has permitted your app to access.

Call a REST API method

To read from or write to a resource such as the Roshambo service, you construct a request that looks like the following:

    {HTTP method} https://www.collybird.com/{resource}?{query-parameters}
    

The components of a request include:

• {HTTP method} - The HTTP method used on the request to }
• {resource} - The resource in Microsoft Graph that you're referencing.
• {query-parameters} - Optional OData query options or REST method parameters that customize the response.

After you make a request, a response is returned that includes:

• Response - The data that you requested or the result of the operation. The response message can be empty for some operations.

HTTP methods

The CollyBird API uses the HTTP method on your request to determine what your request is doing. Depending on the resource, the API may support operations including actions, functions, or CRUD operations described below.

Method	Desription
GET	Read data from a resource.
POST	Create a new resource, or perform an action.
PUT	Replace a resource with a new one.
DELETE	Remove a resource.

• For the CRUD methods GET and DELETE, no request body is required.
• The POST, and PUT methods require a request body, usually specified in JSON format, that contains additional information, such as the values for properties of the resource.

Tools for interacting with the CollyBird

Curl and Postman are tools that you can use to build and test requests using the CollyBird API. Curl is run from the command line and Postman has a GUI.

Example - get an access token

The following example retrieves a list of matches from the Roshambo service.

Request:

    curl 'https://www.collybird.com/api/login' \
        -H 'Accept: application\json' \
        -X POST -d email='[email protected]' \
        -d password='GetSchwifty!' \
        -d device_name='curl-client'    
    

Response:

    {"token":"42|TyXIzXUh5EoxQi7Gqd4fFkNC8TeoLrrUrh7A7OdE"}
    

Example - list Roshambo matches

The following example retrieves a list of matches from the Roshambo service.

Request:

    curl 'https://www.collybird.com/api/roshambo' \
        -H 'Accept: application\json' \
        -H 'Authorization: Bearer 42|TyXIzXUh5EoxQi7Gqd4fFkNC8TeoLrrUrh7A7OdE'
    

Response:

    {"hits":{"found":6,"hit":[{"roshambo_id":"e5cc069e-77e1-40fd-8e85-a87db4241a29","url":"http:\/\/www.collybird.com\/projects\/roshambo\/e5cc069e-77e1-40fd-8e85-a87db4241a29","ourMove":"R","theirMove":"P","opponent":"Patrick","winner":"theirMove"}]}}
    

Example - create a Roshambo match

The following example retrieves a list of matches from the Roshambo service.

Request:

    curl 'https://www.collybird.com/api/roshambo/create' \
        -H 'Accept: application\json' \
        -H 'Authorization: Bearer 42|TyXIzXUh5EoxQi7Gqd4fFkNC8TeoLrrUrh7A7OdE' \
        -X POST -d move='R'    
    

Response:

    {"roshambo_id":"b0df0db4-ff3f-4b68-a9f6-e4d7e2660ce4"}
    

You can explore additional endpoints by authenticating with the API and reading the documentation that accompanies each resource.