ozfortress/citadel

View on GitHub
docs/api/v1.md

Summary

Maintainability
Test Coverage
# Citadel V1 API

This is the documentation for the citadel API (version 1).
It is a read-only JSON API.

Authentication is done using the: `X-API-Key` header.

Path Prefix: `/api/v1`

## Users

### Resource

```
User:
    id: Integer
    name: String
    description: String
    created_at: DateTime(ISO 8601)
    profile_url: String
    steam_32: String
    steam_64: Integer(64)
    steam_id3: String
    teams: [Team]
    rosters: [Roster]

```

### GET `/users/:id`

Options:
- `:id`, the unique id of the user

Example:
```json
{
  "user": {
    "id": 1,
    "name": "/dev/zero",
    "description": "foo bar",
    "created_at": "2016-06-05T17:21:12.371Z",
    "profile_url": "fallback/icon_user_avatar_default.png",
    "steam_32": "STEAM_0:1:38631916",
    "steam_64": 76561198037529561,
    "steam_64_str": "76561198037529561",
    "steam_id3": "U:1:77263833",
    "teams": [
      {
        "id": 2,
        ...
      },
      ...
    ],
    "rosters": [
      {
        "id": 2,
        ...
      },
      ...
    ]
  }
}
```

### GET `/users/steam_id/:steam_id`

Options:
- `:steam_id`, the unique 64 bit steam id of the user

Example same as above.

## Teams

### Resource

```
Team:
    id: Integer
    name: String
    description: String
    avatar_url: String
    avatar_thumb_url: String
    avatar_icon_url: String
    players: [User]
    rosters: [Roster]
```

### GET `/teams/:id`

Options:
- `:id`, the unique id of the team

Example:
```json
{
  "team": {
    "id": 1,
    "name": "Different Mentality",
    "description": "foo bar",
    "avatar_url": "/assets/fallback/team_avatar_default.png",
    "avatar_thumb_url": "/fallback/thumb_team_avatar_default.png",
    "avatar_icon_url": "/fallback/icon_team_avatar_default.png",
    "players": [
      {
        "id": 1,
        ...
      },
      ...
    ],
    "rosters": [
      {
        "id": 1,
        ...
      },
      ...
    ]
  }
}
```

## Leagues

### Resource

```
League:
    id: Integer
    name: String
    description: String
    rosters: [Roster]
    matches: [Match]
```

### GET `/leagues/:id`

Options:
- `:id`, the unique id of the league

Example:
```json
{
  "league": {
    "id": 1,
    "name": "Season 13",
    "description": "foo bar foo",
    "rosters": [
      {
        "id": 2,
        ...
      },
      ...
    ],
    "matches": [
      {
        "id": 3,
        ...
      },
      ...
    ]
  }
}
```

## Rosters

### Resource

```
Roster:
    id: Integer
    name: String
    description: String
    division: String
    disbanded: Boolean
    players: [User]
    matches: [Match]
```

### GET `/rosters/:id`

Options:
- `:id`, the unique id of the roster

Example:
```json
{
  "roster": {
    "id": 1,
    "name": "Some Team",
    "description": "Some info on this roster",
    "division": "Prem",
    "disbanded": false,
    "players": [
      {
        "id": 2,
        ...
      },
      ...
    ],
    "matches": [
      {
        "id": 23,
        ...
      },
      ...
    ]
  }
}
```

## Matches

### Resource

```
Match:
    id: Integer
    forfeit_by: 'no_forfeit' | 'home_team_forfeit' | 'away_team_forfeit' | 'mutual_forfeit' | 'technical_forfeit'
    status: 'pending' | 'submitted_by_home_team' | 'submitted_by_away_team' | 'confirmed'
    round_name: String
    round_number: Integer
    notice: String
    league: League
    home_team: Roster
    away_team: Roster
```

### GET `/matches/:id`

Options:
- `:id`, the unique id of the match

Example:
```json
{
  "match": {
    "id": 22,
    "forfeit_by": "no_forfeit",
    "status": "pending",
    "round_name": "Grand Finals",
    "round_number": 7,
    "notice": "Must be played between Sunday and Thursday",
    "created_at": "2016-11-29T23:52:29.131Z",
    "league": {
      "id": 1,
      ...
    },
    "home_team": {
      "id": 2,
      ...
      "players": [
        {
          "id": 2,
          ...
        },
        ...
      ]
    },
    "away_team": {
      "id": 1,
      ...
      "players": [
        {
          "id": 1,
          ...
        },
        ...
      ]
    },
    "rounds": [
      {
        "away_team_score": 3,
        "home_team_score": 12,
        "map": {
          "id": 1,
          ...
        }
      }
    ]
  }
}
```

## Maps

### Resource

```
Map:
    id: Integer
    name: String
    description: String
```