I've added an API now that should work for Heraldtron integration. I'll happily try to add code myself, but I haven't fully grokked how it works yet, so I thought I'd just document the API as a first step. And perhaps you have certain requirements that could be sorted out here as well.

General

Site: https://heraldicon.org API endpoint: https://2f1yb829vl.execute-api.eu-central-1.amazonaws.com/api Data format:

• I've added JSON support, to avoid the dependency below, all my examples will use JSON
  • required HTTP headers:
    • Content-Type: application/json
    • Accept: application/json
• natively I use edn, which can be read and generated in Python via edn-format

API Functions

generate-from-blazon

POST Payload:

{
  "call": "generate-from-blazon", 
  "data": {
    "blazon": "or, a lion azure langued gules"
  }
}

Success response:

{
  "success": {
    "blazon": "or, a lion azure langued gules",
    "edit-url": "https://heraldicon.org/arms/new?base=905feefa44",
    "png-url": "https://data.heraldicon.org/blazonry-api/png/115905edf022a1c7fd4a1fa06937c6008198a817.png"
  }
}

Example:

curl -H "Content-Type: application/json" -H 'Accept: application/json' https://2f1yb829vl.execute-api.eu-central-1.amazonaws.com/api --data '{"call": "generate-from-blazon", "data": {"blazon": "or, a lion azure langued gules"}}'

The png-url is the rendered arms and edit-url leads to the site to work on the arms with the parsed data already preloaded.

Error handling

If there's an error, then the response will have a HTTP status code of 400 (or 500 for internal server error) and the payload should look like this, e.g. for invalid JSON data:

{
  "error": {
    "message": "Invalid JSON data.",
    "type":"client-invalid-json-data"
  }
}

If there's an error during the parsing of the blazon, then additional data is provided. In this example "langued" is spelled "langed", the index points to the beginning of the word that wasn't understood (langed) and auto-complete -> choices contains a list of [suggestion, suggestion-type] of words that the parser would've expected. The list is ordered by how well the suggestion fits and the type. In this example langued ends up on top. error usually will be null, unless there's an unexpected error... this probably can be ignored. I thought the auto-complete choices could be presented in some clever way as well, perhaps only the first few, if the list is too long and can't be hidden somehow.

{
  "error": {
    "message": "Parser error",
    "type": "client-blazonry-parser-error",
    "data": {
      "value": "or, a lion azure langed gules",
      "error": null,
      "index": 17
      "auto-complete": {
        "choices": [
          ["langued", "extra tincture"],
          ["label", "ordinary"],
          ["labels", "ordinary"],
          ["leaved", "extra tincture"],
          ["legged", "extra tincture"],
          ["lion", "charge"],
          ["lions", "charge"],
          ["lozenge", "charge"],
          ["lozenges", "charge"],
          // ...
        ]
      }
    }
  }
}

Additional options

Additional options can be passed with a list of keywords under the key options:

{
  "call": "generate-from-blazon",
  "data": {
    "blazon": "or, a lion azure langued gules",
    "options": [":swiss", ":squiggly", ":wikipedia-france"]
  }
}

These are just a bunch of special names, but they must be prefixed with a colon. Strings that are not recognized are simply ignored. A list of supported options can be queried programmatically with the next API function, and I think that would be a useful feature for users as well.

blazon-options

Payload:

{
  "call": "blazon-options"
}

Response:

{
  "success": {
    "options": {
      "escutcheon": [
        "english", "flag", "french-modern", "heater", "kite", "lozenge", "none", "norman",
        "norman-rounded", "oval", "polish", "polish-19th-century", "rectangle", "renaissance",
        "roundel", "square-czech", "square-french", "square-iberian", "swiss", "wedge"
      ],
      "mode": ["colours", "hatching"],
      "miscellaneous": ["outline", "shiny", "squiggly"],
      "theme": [
        "all", "community-cmwhyk", "community-content-cranium", "community-cotton-candy",
        "community-crystal-gems", "community-home-world", "community-jewelicious", "community-main-seven",
        "community-mother-earth", "community-pastell-puffs", "community-pretty-soldier", "community-rainbow-groom",
        "community-sodacan", "community-the-monet-maker", "community-van-goes-vroem", "ral-traffic",
        "wappenwiki", "web", "wikipedia-bajuvarian", "wikipedia-brandenburg", "wikipedia-default",
        "wikipedia-france", "wikipedia-hungary", "wikipedia-spain", "wikipedia-sweden", "wikipedia-switzerland",
        "wikipedia-web", "wikipedia-wurttemberg"
      ],
      "texture": [
        "cloth-rough", "cloth-smooth", "felt", "glass-frosted", "marble", "metal-brushed-1",
        "metal-brushed-2", "metal-rough", "metal-scraped", "metal-smooth", "mosaic", "none",
        "satin", "stone", "stone-rough", "wood"
      ]
    }
  }
}

For https://github.com/mirnovov/heraldtron/issues/1

Apologies for the noise, I noticed there was a lot of trailing whitespace, I thought it prudent to get that out of the way to avoid conflicts or noise in later commits.

Also noticed a trailing comma in the schema.

The final commit should be easier to review on its own, tho.

Prefer '+' as prefix for Heraldicon parser options

Both are accepted, so users preferring them or already being used to them can still use them. But + interferes less with Discord, which starts suggesting emojis when a user types :.