Referencia de API de contexto

Bienvenido a la documentación de la API de NPC Builder de context. Esta API te permite gestionar personajes, mundos, regiones y localizaciones dentro de tu juego. A continuación encontrará información detallada sobre cómo utilizar cada endpoint, incluyendo ejemplos de solicitud y respuesta.

Inicia sesión en la app NPC Builder #

Accede a la aplicación web de NPC Builder a través de este enlace: https://app.npcbuilder.com.

Navega a la sección de desarrolladores #

Haz click en el icono de desarrolladores de la barra de navegación.

Genera el token de autenticación #

Haz click en el botón «Generate Bearer Token» y copia el resultado. Guárdalo para después!

En caso de que desee utilizar claves de API para la autenticación, debe pasar los siguientes encabezados:

{
"clientId": "<api_key_id>",
"clientSecret": "<api_key_secret>"
}

Obtén los IDs de tu juego y mundo #

En el árbol que aparece en pantalla, encuentra los IDs asociados al juego y mundo donde se encuentra tu personaje.

Limitaciones técnicas #

  • Debe ceñirse a la estructura de datos definida, de lo contrario puede encontrarse con errores no gestionados.
  • Consulte los esquemas de cada solicitud para conocer los valores permitidos para determinadas propiedades.
  • El conocimiento de los personajes y la actualización y eliminación de relaciones no están disponibles a través de la API. Deben gestionarse a través del frontend de nuestra app.

Construye la petición a la API #

Para más información, consulte la definición completa de la API Swagger.

Actualizar detalles del personaje #

Propiedades permitidas:

  • age: un texto que representa la edad del personaje. Los valores posibles son:
    • «infant»
    • «child»
    • «teenager»
    • «youngAdult»
    • «adult»
    • «middleAged»
    • «elderly»
  • description: un texto que describe el personaje. La longitud máxima es de 1400 caracteres.
  • gender: un texto que representa el género del personaje. Puede ser «Male», «Female» o cualquier otro valor. Si se proporciona «Male» o «Female», debe estar capitalizado.
  • items: un array de objetos que representa los elementos que posee el personaje. Cada elemento tiene:
    • itemName: un texto que representa el nombre del artículo. La longitud máxima es de 25 caracteres.
    • unit: un texto que representa la unidad del artículo. La longitud máxima es de 25 caracteres.
    • value: un texto que representa el valor del artículo. La longitud máxima es de 25 caracteres.
  • name: un texto que representa el nombre del personaje. La longitud máxima es de 25 caracteres.
  • quests: un array de objetos que representa las misiones asociadas con el personaje. Cada misión tiene:
    • description: un texto que representa la descripción de la misión. La longitud máxima es de 125 caracteres.
    • objective: un texto que representa el objetivo de la misión. La longitud máxima es de 125 caracteres.
    • reward: un texto que representa la recompensa de la misión. La longitud máxima es de 125 caracteres.
  • role: un texto que representa el rol del personaje. Los valores posibles son:
    • «noRole»
    • «protagonist»
    • «antagonist»
    • «secondaryCharacter»
    • «tertiaryCharacter»
    • «mentor»
    • «enemy»
    • «villain»
    • «rival»
    • «shopkeeper»
    • «healer»
    • «questGiver»
    • «innkeeper»
    • «guard»
    • «familyMember»
    • «loveInterest»
    • «scientist»
    • «politician»
    • «criminal»
    • «explorer»
    • «wizard»
    • «ghost»
    • «animalCompanion»
    • «artificialIntelligence»
  • tone: un texto que representa el tono del personaje. Los valores posibles son:
    • «formal»
    • «casual»
    • «sarcastic»
    • «mysterious»
    • «emotive»
  • traits: un array de textos que representa los rasgos del personaje. Cada rasgo puede ser cualquier texto, pero no se pueden incluir juntos pares de rasgos opuestos. Los opuestos posibles incluyen:
    • «funny» / «serious»
    • «kind» / «cruel»
    • «generous» / «selfish»
    • «optimistic» / «pessimistic»
    • «brave» / «coward»
    • «arrogant» / «humble»
    • «calm» / «nervous»
    • «polite» / «rude»
    • «joyful» / «sad»
    • «extroverted» / «introverted»
PATCH /characters/{game_id}/{world_id}/{character_id} HTTP/1.1
Host: app.npcbuilder.com
Authorization: Bearer <token>
Content-Type: application/json

{
  "age": "adult",
  "description": "A brave warrior with a mysterious past.",
  "gender": "Male",
  "items": [
    {
      "itemName": "Sword",
      "unit": "Piece",
      "value": "100"
    }
  ],
  "name": "Aragorn",
  "quests": [
    {
      "description": "Retrieve the lost artifact.",
      "objective": "Find and return the artifact.",
      "reward": "500 gold coins"
    }
  ],
  "role": "protagonist",
  "tone": "mysterious",
  "traits": ["brave"]
}
Borrar personaje #
DELETE /characters/{game_id}/{world_id}/{character_id} HTTP/1.1
Host: app.npcbuilder.com
Authorization: Bearer <token>
Actualizar detalles del mundo #

Propiedades permitidas:

  • lore: un texto que representa la historia del mundo. La longitud máxima es de 1400 caracteres.
  • name: un texto que representa el nombre del mundo. La longitud máxima es de 25 caracteres.
  • creatures: un texto que representa las criaturas en el mundo. La longitud máxima es de 75 caracteres.
  • similarWorlds: un array de textos que representa mundos similares.
PATCH /world/{game_id}/{world_id} HTTP/1.1
Host: app.npcbuilder.com
Authorization: Bearer <token>
Content-Type: application/json

{
  "lore": "A world where magic and technology coexist.",
  "name": "Eldoria",
  "creatures": "Dragons, Elves",
  "similarWorlds": ["Middle Earth"]
}
Borrar mundo #
DELETE /world/{game_id}/{world_id} HTTP/1.1
Host: app.npcbuilder.com
Authorization: Bearer <token>
Actualizar detalles de la región #

Propiedades permitidas:

  • lore: un texto que representa la historia de la región. La longitud máxima es de 1400 caracteres.
  • name: un texto que representa el nombre de la región. La longitud máxima es de 25 caracteres.
  • weather: un texto que representa el clima en la región. La longitud máxima es de 25 caracteres.
  • culture: un texto que representa la cultura de la región. La longitud máxima es de 125 caracteres.
  • politicalStability: un texto que representa la estabilidad política de la región. Los valores posibles son:
    • «none»
    • «highlyStable»
    • «stable»
    • «moderatelyStable»
    • «unstable»
    • «highlyUnstable»
    • «anarchy»
PATCH /region/{game_id}/{world_id}/{region_id} HTTP/1.1
Host: app.npcbuilder.com
Authorization: Bearer <token>
Content-Type: application/json

{
  "lore": "A dense forest with hidden secrets.",
  "name": "Mystic Forest",
  "weather": "Rainy",
  "culture": "Druidic traditions",
  "politicalStability": "stable"
}
Borrar región #
DELETE /region/{game_id}/{world_id}/{region_id} HTTP/1.1
Host: app.npcbuilder.com
Authorization: Bearer <token>
Actualizar detalles de la localización #

Propiedades permitidas:

  • lore: un texto que representa la historia de la ubicación. La longitud máxima es de 1400 caracteres.
  • name: un texto que representa el nombre de la ubicación. La longitud máxima es de 25 caracteres.
  • role: un texto que representa el rol de la ubicación. La longitud máxima es de 25 caracteres.
PATCH /location/{game_id}/{world_id}/{location_id} HTTP/1.1
Host: app.npcbuilder.com
Authorization: Bearer <token>
Content-Type: application/json

{
  "lore": "A bustling market town.",
  "name": "Rivertown",
  "role": "Trade hub"
}
Borrar localización #
DELETE /location/{game_id}/{world_id}/{location_id} HTTP/1.1
Host: app.npcbuilder.com
Authorization: Bearer <token>

Swagger #