Skip to content

API

Jump to bottom Edit New page
Steven Soloff edited this page Jul 27, 2017 · 19 revisions

Services

evaluate-expression

Request

Property Value
Endpoint /api/expression/evaluate
Method POST
Content type application/json
Body EvaluateExpressionRequest

Response (success)

Property Value
Content type application/json
Body EvaluateExpressionResponse

Response (failure)

Property Value
Content type application/json
Body ErrorResponse

issue-ticket

Request

Property Value
Endpoint /api/ticket/issue
Method POST
Content type application/json
Body IssueTicketRequest

Response (success)

Property Value
Content type application/json
Body IssueTicketResponse

Response (failure)

Property Value
Content type application/json
Body ErrorResponse

redeem-ticket

Request

Property Value
Endpoint /api/ticket/redeem
Method POST
Content type application/json
Body RedeemTicketRequest

Response (success)

Property Value
Content type application/json
Body RedeemTicketResponse

Response (failure)

Property Value
Content type application/json
Body ErrorResponse

validate-redeemed-ticket

Request

Property Value
Endpoint /api/ticket/validate-redeemed
Method POST
Content type application/json
Body ValidateRedeemedTicketRequest

Response (success)

Property Value
Content type application/json
Body ValidateRedeemedTicketResponse

Response (failure)

Property Value
Content type application/json
Body ErrorResponse

Types

DieRollResult

A die roll result.

{
  "sides": <sides:Number!>,
  "value": <value:Number!>
}
Property Description
sides The count of sides the die possesses.
value The value of the die roll.

ErrorResponse

A response to a service request in which an error occurred.

{
  "error": {
    "message": <errorMessage:String!>
  }
}
Property Description
errorMessage A message describing the error, which is suitable for display to the end user.

EvaluateExpressionRequest

A request sent to the evaluate-expression service.

{
  "expression": {
    "text": <expressionText:String!>
  }
}
Property Description
expressionText The expression to be evaluated.

EvaluateExpressionResponse

A response received from the evaluate-expression service.

{
  "dieRollResults": <dieRollResults:DieRollResult[]!>,
  "expression": {
    "canonicalText": <expressionCanonicalText:String!>,
    "text": <expressionText:String!>,
  },
  "expressionResult": {
    "text": <expressionResultText:String!>,
    "value": <expressionResultValue:Number!>
  },
  "randomNumberGenerator": <randomNumberGenerator:RandomNumberGenerator!>
}
Property Description
dieRollResults An array of DieRollResults. There will be one DieRollResult for each die rolled in the expression.
expressionCanonicalText The canonical text of the expression specified in the request. The canonical text is created by the server by parsing the expression and then re-formatting it.
expressionText The expression text as specified in the request.
expressionResultText The expression result text. This text contains the results of all intermediate subexpressions, e.g. die rolls.
expressionResultValue The numerical value of evaluating the expression.
randomNumberGenerator A RandomNumberGenerator object that describes the RNG that was used to generate any random values during expression evaluation (e.g. when rolling dice).

IssueTicketRequest

A request sent to the issue-ticket service.

{
  "description": <description:String!>,
  "evaluateExpressionRequestBody": <evaluateExpressionRequestBody:EvaluateExpressionRequest!>
}
Property Description
description Describes the purpose of the ticket (e.g. John's attack roll).
evaluateExpressionRequestBody An EvaluateExpressionRequest object that describes the expression to evaluate when the ticket is redeemed.

IssueTicketResponse

A response received from the issue-ticket service.

{
  "ticket": {
    "content": {
      "description": <description:String!>,
      "evaluateExpressionRequestBody": <evaluateExpressionRequestBody:EvaluateExpressionRequest!>,
      "id": <id:String!>,
      "redeemUrl": <redeemUrl:String!>
    },
    "signature": <signature:Signature!>
  }
}
Property Description
description The ticket description specified in the request.
evaluateExpressionRequestBody The EvaluateExpressionRequest object specified in the request.
id The ticket identifier.
redeemUrl The URL at which the ticket must be redeemed.
signature A Signature that can be used to confirm the validity of the ticket.

RandomNumberGenerator

A description of a random number generator.

{
  "name": <name:String!>
}
Property Description
name The random number generator name. The only supported value in production is uniform, which indicates a uniform pseudo-random number generator. Thus, this object will actually be an instance of UniformRandomNumberGenerator.

RedeemTicketRequest

A request sent to the redeem-ticket service. This object is identical to the IssueTicketResponse object. The response body received from the issue-ticket service is intended to be sent unmodified as the request body to the redeem-ticket service.

RedeemTicketResponse

A response received from the redeem-ticket service.

{
  "redeemedTicket": {
    "content": {
      "description": <description:String!>,
      "evaluateExpressionResponseBody": <evaluateExpressionResponseBody:EvaluateExpressionResponse!>,
      "id": <id:String!>,
      "validateUrl": <redeemUrl:String!>
    },
    "signature": <signature:Signature!>
  }
}
Property Description
description The ticket description specified by the requester.
evaluateExpressionResponseBody The EvaluateExpressionResponse object that contains the result of evaluating the expression specified in the ticket.
id The ticket identifier.
validateUrl The URL at which the redeemed ticket must be validated.
signature A Signature that can be used to confirm the validity of the redeemed ticket.

Signature

A detached JSON web signature that can be used to validate sibling content. See the security module for details on the structure of a detached JSON web signature, including how to validate the signature.

UniformRandomNumberGenerator

A description of a uniform random number generator.

{
  "name": "uniform",
  "options": <options:UniformRandomNumberGeneratorOptions=>
}
Property Description
name This property will always have the value uniform.
options A UniformRandomNumberGeneratorOptions object that specifies how to configure the RNG. If not specified, a default set of options are used.

UniformRandomNumberGeneratorOptions

A set of options used to configure a uniform random number generator.

{
  "seed": <seed:Number=|Number[]=>
}
Property Description
seed The seed used to initialize the RNG. Can be either a number or an array of numbers. If not specified, a default seed is used.

ValidateRedeemedTicketRequest

A request sent to the validate-redeemed-ticket service. This object is identical to the RedeemTicketResponse object. The response body received from the redeem-ticket service is intended to be sent unmodified as the request body to the validate-redeemed-ticket service.

ValidateRedeemedTicketResponse

A response received from the validate-redeemed-ticket service.

{
}

Security

Certain content in an API response may be signed by DSJS to ensure the integrity of the data. For example, to reassure a game master that a die roll has not been modified by a player after it was evaluated by DSJS. Users of DSJS can verify the integrity of the signed content by validating the appropriate signature using the DSJS public key.

The DSJS public keys are provided below in PKCS#8 PEM-encoded format. To ensure the DSJS public key you possess has not been tampered with, you can calculate its fingerprint and compare it to one of the published fingerprints below (ensure you are viewing this page via HTTPS).

Public keys

Production

   
Public key 
-----BEGIN PUBLIC KEY-----
MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAx9fDJmxiSzEctbimp+ML
SB0mBE42ioGsebyclDgovgkMTqcsgPqa2qq/FToxCYODU6YTN0KbJCQvV3qW2Zp6
2Y2ju0vmdEyC0TDFMAJEdri5GfO111vt3In8XB0yq9q9mPWmRziMgvqpJYnJyRH8
NIorn1VvloPX0ELSEhbeae5HTGWVpxF8NLU9Epu2NQsLKLrj3PTW6dcJ00jALsjY
6AQzaS1bfoB44FbP0vMQcQ41TETAjBZpKr7gi3qC4hSF+E/XKhjicrKtJSGECLO/
0+urhSf7ku5Htio2wT/MlPGxRR1bK2Eoyl9/20N+HQP0BeZh1G8PoS/Y8KyNulrX
EwIDAQAB
-----END PUBLIC KEY-----
Download
Fingerprint (OpenSSH) SHA256:KfbqJJFPw+AhpFQZrtaa2cnS27pzQ+VfBowzquB+BK4
Fingerprint (OpenSSL) 6cff1bf490f0b84cbbd5e1c26990d933746fd4c8318adc037a5584e752032d4e

Staging

   
Public key 
-----BEGIN PUBLIC KEY-----
MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA1mGErgb4Vyp6e2263m7g
IhbDUjlqrpv+sM24SAVrkPb1uw66F4qfWzQfmZTnd0mvaet5KZTT9BWYXnNhJTDQ
don/KFrcUqA6bO2bOJdiMPZ62c+CB8EgLMI5gaSnU4FT9C6onsGndIq5dp7+pZMJ
PPx6jQN3w6+WlFxNovDc6G+pje+hIFlgDtwt386uZO75Acg/fQB4qiGFFZ51Z+ip
4+tVkCxD8DKVW2c5ny3wta+GvReMfqH8Imn7x+psUKeYc3736D/fpXd9JN98Y+F9
wxZmhANFu5bQqbdxldIviN833mC8f/qXuID1vbTAcX+t6hcXeR2UYEjHz6TMK8vx
zQIDAQAB
-----END PUBLIC KEY-----
Download
Fingerprint (OpenSSH) SHA256:fXOnLHdpLSTThpnPD+RABj7rdKQAbpt87l4iucAkfos
Fingerprint (OpenSSL) 6e580163ae9d7b39667358dda152c9e6fc91dd2ae922d8221c13f46ae6cea407

Calculating public key fingerprints

Instructions for calculating the public key fingerprint are given below (the examples assume you have saved the public key in a file named public-key.pem).

Tool Command
OpenSSH ssh-keygen -if public-key.pem -m pkcs8 | ssh-keygen -lf -
OpenSSL openssl rsa -pubin -in public-key.pem -outform DER | sha256sum
Add a custom footer
Add a custom sidebar
Clone this wiki locally