oauth

In the case of our favorite original tester, Grizzly, requesting his information would take the following form:

curl -H "Authorization: Bearer abc123" GET https://pethub.io/v1/pets/223

The above authorized call to PetHub.io's "/v1/pets/{id}" endpoint with Grizzly's unique identifier (where "223" replaces the "{id}") would receive the following response:

{
    "pid": "223",
    "uid": "66",
    "name": "Grizzly",
    "species": {
      "tid": "3031"
    },
    "breed_primary": {
      "target_id": "2855"
    },
    "breed_mix": "Chihuahua",
    "gender": "Male",
    "picture": {
      "fid": "189",
      "uid": "66",
      "filename": "grizzly.jpg",
      "filemime": "image/jpeg",
      "filesize": "7735",
      "status": "1",
      "timestamp": "1414801248",
      "type": "image",
      "metadata": {
        "height": 280,
        "width": 186
      },
      "height": "280",
      "width": "186",
      "url": "https://images.pethub.com/dev/pub/grizzly.jpg?milgJeq.a.UHYX6vfvnF7f2alm0p1Y5H"
    },
    "birthday": "2013-11-16 00:00:00",
    "size": {
      "tid": "3236"
    },
    "weight_value": "4",
    "weight_unit": "lb",
    "coat": "Short Hair",
    "tail": {
      "tid": "3428"
    },
    "altered": {
      "value": "Yes"
    },
    "description": "Our precious fuzzi-wuzzums.",
    "microchip": ""
  }

The format of the data above is JSON which is the default format typically specified in the Header as part of the request. However, if necessary, the format can be explicitly requested by appending ".json" or ".xml" to the noun to receive JSON or XML formatted data, respectively. For example:

curl -H "Authorization: Bearer abc123" GET https://pethub.io/v1/pets.json/223

With a few exceptions, the PetHub API is generally accessed through HTTP request methods (e.g. GET, POST, PUT, DELETE) that follow a general pattern:

https://pethub.io/v1/{noun}
https://pethub.io/v1/{noun}/{id}
https://pethub.io/v1/{noun}/{id}/{type}

The "v1" is simply to help us provide versioning with our APIs. That way when we start working on a version 2 will can void disrupting any applications utilizing the previous version. The {noun} is the type of resource that is being worked with and the {id} is the identifier for a specific resource being acted upon. The {type} parameter allows for a scoped search in certain situations.

Part of authenticating each request is the use of the aforementioned access token that is passed as part of the header in the request. Using cURL as an example of what this might look like, the request would look similar to the following:

curl -H "Authorization: Bearer {access_token}" GET
https://pethub.io/v1/{noun}/{id}

See the documentation on Authentication for additional details about obtaining the value that would replace the {access_token} entry shown above. Also, for the sake of clarity, please note that the curly braces are a documentation preference and not literally included when substituting your actual values. For example, if your access token were "abc123" and the noun was "pets" and the individual pet's ID was 321, the statement using the above syntax would be:

curl -H "Authorization: Bearer abc123" GET
https://pethub.io/v1/pets/321

Further Explanation

Exploring the above example further, let's dissect this statement to better understand it:

• curl - this is the command-line tool for transferring data (cURL)
•  -H - the "-H" or "--header" option allows custom header settings to be passed to the server (in this case, we are adding in the "Authorization: Bearer abc123" string to the header as part of the request)
• GET - the HTTP method being used in this request to the server followed by the URL

If the endpoint supports parameters, those can be included as part of the URL.

PetHub uses OAuth for secure authentication.

To get started you need to:

1. Submit an API Key Request form
2. Create a PetHub.io account (invitation only - details provided when API key is assigned)
3. Send requests to our servers with proper authentication (e.g. you can use cURL for testing)

Once you have your API Key and Secret, combined those can be used to request an access token. It is this token that is passed with each API request sent to our servers.

To get an access token, simply make the following request (replacing {API-KEY} and {API-SECRET} with the information associated with your account):

curl -d "request_type=api_credentials&api_key={API-KEY}&api_secret={API-SECRET}"
https://pethub.io/v1/oauth2/token

The PetHub.io server will send back a response similar to the following:

{
    "token_type": "Bearer",
    "expires_in": 1800,
    "access_token": "some-alphanumeric-token"
}