Introduction

Here you can find the documentation about Octagon API. This API is designed to provide data about professional fighters categorized across various weight divisions in MMA.

This documentation will guide you through the available endpoints, parameters, and response formats to help you integrate this data into your applications or services.

If you have any questions, encounter issues, or need further assistance, feel free to open an issue on GitHub or reach out to me at fentos.dev@gmail.com.

In this table, you will find a summary of the endpoints.

GET /rankings

This endpoint returns the whole rankings data.

The JSON data is an array, where each entry is an object with the properties listed in the table.

[
  {
    "id": "mens-pound-for-pound-top-rank",
    "categoryName": "Men's Pound-for-Pound Top Rank",
    "champion": {
      "id": "islam-makhachev",
      "championName": "Islam Makhachev"
    },
    "fighters": [
      {
        "id": "islam-makhachev",
        "name": "Islam Makhachev"
      },
      {
        "id": "alex-pereira",
        "name": "Alex Pereira"
      }
      // More fighters...
    ]
  },
  {
    "id": "flyweight",
    "categoryName": "Flyweight",
    "champion": {
      "id": "alexandre-pantoja",
      "championName": "Alexandre Pantoja"
    },
    "fighters": [
      {
        "id": "brandon-royval",
        "name": "Brandon Royval"
      },
      {
        "id": "brandon-moreno",
        "name": "Brandon Moreno"
      }
      // More fighters...
    ]
    // More divisions...
  }
]

GET /fighters

This endpoint returns the whole fighters data.

The JSON data is an Object, where each key is the unique identifier of a fighter.

The value is an object containing various details about the fighter. The properties of each fighter object are listed in the table, providing information such as the fighter’s division, record, personal details, and physical attributes.

{
  "islam-makhachev": {
    "category": "Lightweight Division",
    "draws": "0",
    "imgUrl": "https://dmxg5wxfqgb4u.cloudfront.net/styles/athlete_bio_full_body/s3/2024-05/MAKHACHEV_ISLAM_L_BELT_06-01.png?itok=O8gDxptU",
    "losses": "1",
    "name": "Islam Makhachev",
    "nickname": "",
    "wins": "26",
    "status": "Active",
    "placeOfBirth": "Dagestan Republic, Russia",
    "trainsAt": "AKA (American Kickboxing Academy) San Jose",
    "fightingStyle": "Sambo",
    "age": "32",
    "height": "70.00",
    "weight": "155.00",
    "octagonDebut": "May. 23, 2015",
    "reach": "70.50",
    "legReach": "40.50"
  }
  // More fighters...
}

GET /fighter/:fighterId

This endpoint returns the concrete fighterId data.

The JSON data is an Object containing various details about the fighter. These properties are listed in the table, providing information such as the fighter’s division, record, personal details, and physical attributes.

{
  "category": "Heavyweight Division",
  "draws": "0",
  "imgUrl": "https://dmxg5wxfqgb4u.cloudfront.net/styles/athlete_bio_full_body/s3/2023-03/JONES_JON_L_BELT_03_04.png?itok=P6J6DQpm",
  "losses": "1",
  "name": "Jon Jones",
  "nickname": "Bones",
  "wins": "27",
  "status": "Active",
  "placeOfBirth": "Rochester, United States",
  "age": "35",
  "height": "76.00",
  "weight": "248.00",
  "octagonDebut": "Aug. 9, 2008",
  "reach": "84.50",
  "legReach": "45.00"
}

GET /division/:divisionId

This endpoint returns the concrete divisionId data.

The JSON data is an Object that represents a division of fighters, containing properties such as the category ID, category name, champion details, and an array of fighters with their respective IDs and names, as outlined in the table.

{
  "id": "flyweight",
  "categoryName": "Flyweight",
  "champion": {
    "id": "alexandre-pantoja",
    "championName": "Alexandre Pantoja"
  },
  "fighters": [
    {
      "id": "brandon-royval",
      "name": "Brandon Royval"
    },
    {
      "id": "brandon-moreno",
      "name": "Brandon Moreno"
    }
    // More fighters...
  ]
}

GraphQL API

In addition to our REST endpoints, we offer a GraphQL API for more flexible and efficient data querying. GraphQL allows you to request exactly the data you need in a single query, reducing over-fetching and under-fetching of data.

GraphQL Endpoint

POST https://api.octagon-api.com/graphql

Schema Overview

Our GraphQL schema includes the following main types:

• Query: The entry point for all GraphQL queries
• Division: Represents a weight division
• Fighter: Represents a fighter
• Champion: Represents a champion of a division

Example Queries

1. Get all rankings with champions and fighters:

query {
  rankings {
    id
    categoryName
    champion {
      id
      championName
    }
    fighters {
      id
      name
    }
  }
}

2. Get detailed information about a specific fighter:

query {
  fighter(id: "jon-jones") {
    name
    nickname
    category
    wins
    losses
    draws
    status
    age
    height
    weight
    reach
    legReach
  }
}

3. Get information about a specific division:

query {
  division(id: "flyweight") {
    categoryName
    champion {
      championName
    }
    fighters {
      name
      wins
      losses
    }
  }
}

Using GraphQL in Your Application

To use our GraphQL API:

1. Send a POST request to https://api.octagon-api.com/graphql
2. Set the Content-Type header to application/json
3. In the request body, include a JSON object with a query key containing your GraphQL query

Example using curl:

curl -X POST \
  -H "Content-Type: application/json" \
  -d '{"query": "{ fighter(id: \"jon-jones\") { name category wins losses } }"}' \
  https://api.octagon-api.com/graphql

Benefits of Using GraphQL

• Flexible Queries: Request multiple resources in a single query
• Precise Data Fetching: Get only the data you need, nothing more, nothing less
• Strongly Typed: The schema provides clear expectations about the structure of the data
• Introspection: Explore the available data and schema using GraphQL introspection

GraphQL Playground

For interactive exploration of our GraphQL API, you can use the GraphQL Playground available at:

https://api.octagon-api.com/graphql

This web-based tool allows you to write and execute queries, explore the schema, and view documentation.

For more information on how to use GraphQL, please refer to the official GraphQL documentation.