Introduction

Welcome to the Kittn API! You can use our API to access Kittn API endpoints, which can get information on various cats, kittens, and breeds in our database.

We have language bindings in Shell, Ruby, and Python! You can view code examples in the dark area to the right, and you can switch the programming language of the examples with the tabs in the top right.

This example API documentation page was created with Slate. Feel free to edit it and use it as a base for your own API's documentation.

Code Structure

Since FirstTouch relies on Trailblazer approach, most of our actions have an operation associated. For each action there will be the explanation on how to run the operation in the terminal.

Authentication

FirstTouch uses API keys to allow access to the API. You can register a new user to get the FirstTouch API key through the signup page or running the register operation directly on the rails console.

FirstTouch expects for the API key to be included in all API requests to the server in a header that looks like the following:

Authorization: meowmeowmeow

Platform Generic API endpoints

Playing Positions

FirstTouch::PLAYING_POSITIONS

The above command returns JSON structured like this:

[
  "Goalkeeper",
  "Sweeper (Centre)",
  "Defender (Right)",
  "Defender (Left)",
  "Defender (Centre)",
  "Wing-back (Right)",
  "Wing-back (Left)",
  "Defensive Midfielder (Centre)",
  "Midfielder (Right)",
  "Midfielder (Left)",
  "Midfielder (Centre)",
  "Attacking Midfielder (Centre)",
  "Winger (Right)",
  "Winger (Left)",
  "Second Striker (Centre)",
  "Striker (Centre)"
]

This endpoint allows the requester to fetch the possible playing positions.

HTTP Request

GET http://example.com/api/v1/settings/playing_positions

Users

Sign up/Register

::V1::User::Register.(params: params)

The above command returns JSON structured like this:

{
  "user": {
    "id": 10,
    "career_history": [],
    "personal_profile": {
      "id": 13,
      "first_name": "Rui",
      "middle_name": "Pedro",
      "last_name": "Baltazar",
      "birthday": "1998-02-10",
      "nationality_country_code": "PT",
      "residence_country_code": "SG",
      "place_of_birth": "Coimbra",
      "weight": "37",
      "height": "137",
      "preferred_foot": "both",
      "languages": ["PT", "EN", "IT"],
      "playing_positions": [
        { "position": "Goalkeeper", "skill": "[0-5]" }
      ],
      "pro_status": "Amateur",
      "total_caps": 0
    }
  }
}

This endpoint allows a new user to be registered. After being registered, an email is sent to the user to confirm the email address thus confirming the account. Only after confirming the email address the user will be able to login.

HTTP Request

GET http://example.com/api/v1/users/register

Query Parameters

Parameter	Mandatory	Default	Description
email	Y		User registration email
password	Y		User's preferred password
password_confirmation	Y		Double checking of password
role_name	Y		Which role is the user registering as. Choice from player, manager, coach, scout, director
club_ids	Y		Which club is the user associated with, if any
personal_profile	Y		key for personal profile attributes

The following attributes can/have to be passed in the personal_profile

Parameter	Mandatory	Default	Description
first_name	Y		User's first name
middle_name	N		User's middle name
last_name	Y		User's last name
birthday	Y		User's birthday
nationality_country_code	N		Players nationality country code
residence_country_code	N		Players residence country code
weight	N		Players weight in Kg
height	N		Players height in cm
preferred_foot	N		Preferred foot
playing_positions	N		JSON Array with the following structure per playing position: { position: , skill: <0-5> }
pro_status	N		Professional status

Login

The above command returns JSON structured like this:

{
 "auth_token": "amazing_api_key"
}

This endpoint allows a user to fetch the users authorization key.

HTTP Request

GET http://example.com/api/v1/authenticate

Query Parameters

Parameter	Mandatory	Default	Description
email	Y		User email
password	Y		User's password

Public Profile

::V1::User::Show.(params: params)

The above command returns JSON structured like this:

{
  "id": 2,
  "following": false,
  "personal_profile": {
    "id": 7
  },
  "connection_status": "pending"
}

This api endpoint should be used to fetch a particular user's profile

HTTP Request

GET http://example.com/api/v1/users/:id/profile

Query Parameters

Parameter	Mandatory	Default	Description
id	Y		Requested User Id

Personal Profile

The above command returns JSON structured like this:

{
  "id": 2,
  "career_history": [],
  "personal_profile": {
    "id": 13,
    "first_name": "Rui",
    "middle_name": "Pedro",
    "last_name": "Baltazar",
    "birthday": "1998-02-10",
    "nationality_country_code": "PT",
    "residence_country_code": "SG",
    "place_of_birth": "Coimbra",
    "weight": "37",
    "height": "137",
    "preferred_foot": "both",
    "languages": ["PT", "EN", "IT"],
    "playing_positions": [
      { "position": "Goalkeeper", "skill": "[0-5]" }
    ],
    "pro_status": "Amateur",
    "total_caps": 0,
    "avatar_url": "https://images.google.com/img1.png"
  }
}

This api endpoint should be used to fetch a particular user's profile

HTTP Request

GET http://example.com/api/v1/user

Query Parameters

N.A

Update Personal Profile

::V1::User::Update.(params: params, current_user: current_user)

The above command returns JSON structured like this:

{
  "id": 2,
  "career_history": [],
  "personal_profile": {
    "id": 13,
    "first_name": "Rui",
    "middle_name": "Pedro",
    "last_name": "Baltazar",
    "birthday": "1998-02-10",
    "nationality_country_code": "PT",
    "residence_country_code": "SG",
    "place_of_birth": "Coimbra",
    "weight": "37",
    "height": "137",
    "preferred_foot": "both",
    "languages": ["PT", "EN", "IT"],
    "playing_positions": [
      { "position": "Goalkeeper", "skill": "[0-5]" }
    ],
    "pro_status": "Amateur",
    "total_caps": 0,
    "avatar_url": "https://images.google.com/img1.png"
  }
}

This api endpoint should be used to fetch a particular user's profile

HTTP Request

POST http://example.com/api/v1/user

Query Parameters

Parameter	Mandatory	Default	Description
personal_profile	Y		User's personal profile holder. It follows the next table params

Parameter	Mandatory	Default	Description
first_name	Y		String with First Name
middle_name			String with Middle Name
last_name	Y		String with Last Name
birthday	Y		String with Birthday. Preferred format: YYYY-MM-DD
nationality_country_code			Country code in ISO Format
residence_country_code			Country code in ISO Format
place_of_birth			String with place of birth
weight			Float with weight
height			Float with height
preferred_foot			Choice between: [right, left, both]
playing_positions			Array with playing positions and skill. E.g. [{ "position": "Goalkeeper", "skill": 5 }]. Available playing positions: [Goalkeeper, Sweeper (Centre), Defender (Right), Defender (Left), Defender (Centre), Wing-back (Right), Wing-back (Left), Defensive Midfielder (Centre), Midfielder (Right), Midfielder (Left), Midfielder (Centre), Attacking Midfielder (Centre), Winger (Right), Winger (Left), Second Striker (Centre), Striker (Centre)]
pro_status			Choice between: [professional, semi-professional, amateur]
biography			Text with user's biography

Update Personal Avatar

::V1::User::Update.(params: params, current_user: current_user)

The above command returns JSON structured like this:

{
  "id": 2,
  "career_history": [],
  "personal_profile": {
    "id": 13,
    "first_name": "Rui",
    "middle_name": "Pedro",
    "last_name": "Baltazar",
    "birthday": "1998-02-10",
    "nationality_country_code": "PT",
    "residence_country_code": "SG",
    "place_of_birth": "Coimbra",
    "weight": "37",
    "height": "137",
    "preferred_foot": "both",
    "languages": ["PT", "EN", "IT"],
    "playing_positions": [
      { "position": "Goalkeeper", "skill": "[0-5]" }
    ],
    "pro_status": "Amateur",
    "total_caps": 0,
    "avatar_url": "https://images.google.com/img1.png"
  }
}

This api endpoint should be used to fetch a particular user's profile

HTTP Request

POST http://example.com/api/v1/user/avatar

Query Parameters

Parameter	Mandatory	Default	Description
avatar	Y		formData with new image

Career Entries

Create

::V1::CareerEntry::Create.(params)

The above command returns JSON structured like this:

{
  "career_entry": {
    "id": 10,
    "start_date": "1998-02-10",
    "end_date": "1999-02-10",
    "club": {
      "id" : 2,
      "name": "F. C. Barcelona"
    }
  }
}

This endpoint allows a new user to be registered.

HTTP Request

POST http://example.com/api/v1/career_entries

Query Parameters

Parameter	Mandatory	Default	Description
club_id	Y		Club which the user represented
start_date	Y		Career entry Start date
end_date	N		Career entry End date. Might be nil which would mean ongoing
role_name	Y		Which role the user was representing: player, manager, coach, scout, director

Update

::V1::CareerEntry::Update.(params)

The above command returns JSON structured like this:

{
  "career_entry": {
    "id": 10,
    "start_date": "1998-02-10",
    "end_date": "1999-02-10",
    "club": {
      "id" : 2,
      "name": "F. C. Barcelona"
    }
  }
}

This endpoint allows a new user to be registered.

HTTP Request

PUT http://example.com/api/v1/career_entries/10

Query Parameters

Parameter	Mandatory	Default	Description
club_id	Y		Club which the user represented
start_date	Y		Career entry Start date
end_date	N		Career entry End date. Might be nil which would mean ongoing
role_name	Y		Which role the user was representing: player, manager, coach, scout, director

Delete

::V1::CareerEntry::Delete.(params)

The above command returns JSON structured like this:

{
  "career_entry": {
    "id": 10
  }
}

This endpoint allows a new user to be registered.

HTTP Request

DELETE http://example.com/api/v1/career_entries/10

Query Parameters

-

Clubs

Search

::V1::Club::Index.(params)

The above command returns JSON structured like this:

{
  "clubs": [{
    "id": 1,
    "name": "Bananas",
    "city": "City",
    "country_code": "PT"
  }]
}

This endpoint to search for a club. It allows searching by a keyword using q param or a country code using country param, or both combined

HTTP Request

GET http://example.com/api/v1/clubs/search

Query Parameters

Parameter	Mandatory	Default	Description
q	N		Keyword to match club's name
country	N		ISO Country Code to filter the clubs

Countries

::V1::Club::Countries.()

The above command returns JSON structured like this:

{
  "countries": [{
      "country_name": "Portugal",
      "country_code": "PT"
    },
    {
      "country_name": "United States of America",
      "country_code": "US"
    }
  ]
}

This endpoint is used to fetch the countries for which we have clubs available in the database.

HTTP Request

GET http://example.com/api/v1/clubs/countries

Query Parameters

Parameter	Mandatory	Default	Description

Notes

Create

::V1::Note::Create.(params, current_user: user)

The above command returns JSON structured like this:

{
  "id": 4,
  "user_id": 8,
  "name": "test",
  "content": "hello",
  "labels": [
    "one",
    "two",
    "three"
  ]
}

This endpoint allows a new user to be registered.

HTTP Request

POST http://example.com/api/v1/notes

Query Parameters

These params should be passed inside key note

Parameter	Mandatory	Default	Description
labels	N	[]	Array of labels associated with the note
name	Y		Note name
password_confirmation	Y		Double checking of password
role_name	Y		Which role is the user registering as. Choice from player, manager, coach, scout, director
personal_profile	Y		key for personal profile attributes

The following attributes can/have to be passed in the personal_profile

Parameter	Mandatory	Default	Description
first_name	Y		User's first name
middle_name	N		User's middle name
last_name	Y		User's last name
birthday	Y		User's birthday
club_id	Y		Which club is the user associated with, if any
nationality_country_code	N		Players nationality country code
residence_country_code	N		Players residence country code
weight	N		Players weight
height	N		Players height
preferred_foot	N		Preferred foot
playing_position	N		Playing position
pro_status	N		Professional status

Login

The above command returns JSON structured like this:

{
 "auth_token": "amazing_api_key"
}

This endpoint allows a user to fetch the users authorization key.

HTTP Request

GET http://example.com/api/v1/authenticate

Query Parameters

Parameter	Mandatory	Default	Description
email	Y		User email
password	Y		User's password

Public Profile

::V1::User::Show.(params)

The above command returns JSON structured like this:

{
  "id": 2,
  "following": false,
  "personal_profile": {
    "id": 7
  },
  "connection_status": "pending"
}

This api endpoint should be used to fetch a particular user's profile

HTTP Request

GET http://example.com/api/v1/users/:id/profile

Query Parameters

Parameter	Mandatory	Default	Description
id	Y		Requested User Id

Errors

In FirstTouch we use a concept of Endpoint where all the generic error codes are defined. These are the errors that the API might produce:

Error Code	Meaning
422	Unprocesseable entity -- Your request is invalid.
401	Unauthorized -- Your API key does not allow you to perform this action.
404	Not Found -- The specified resource could not be found.
500	Internal Server Error -- We had a problem with our server. Try again later.
503	Service Unavailable -- We're temporarily offline for maintenance. Please try again later.