Api Documentation

The formatting service is hosted as an azure function. Initial use will probably take some time (due to the warming of the azure function) but subsequent usages should be much quicker.

Terms of use

You are free to use the api as long as you give credit and (if you use the formatter for your website) embed a backlink to https://www.durchblick-durch-daten.de/power-query/m-formatter/ . If you use the api you agree to the following conditions:
  • The service is provided "as is" without warranty of any kind
  • We do not save any queries or any meta data with the exception of Error tracking. We track Errors that occur on during formatting in order to fix bugs and improve our service. In these cases meta data about the Error is sent to the azure app insights remote service which contains a stacktrace. This stacktrace might indirectly contain some information about the query that caused the error
We provide our service as is and give no warranty about the results

How to use

To use the api you need to send a POST request to https://m-formatter.azurewebsites.net/api/v2 . A javascript usage example is provided in our example repository.
The body of the request is a flat object and can either be provided by a Content-Type application/x-www-form-urlencoded or application/json. Required fields are only code and resultType. The resultType determines which additional non required options you can provide to the formatter and what kind of result you want to have. The property resultType can have 4 values
  • text: returns a json object that contains the formatted plain text (Content-Type: application/json)
  • html: returns a json object that contains the formatted code as HTML (Content-Type: application/json)
  • codeblock: returns a json object that contains the formatted HTML embedded in a codeblock (Content-Type: application/json). Note that the emitted codeblock HTML needs to be styled by your embedding page. You can have a look at the styles we use for the codeblock with a dark and light theme here (sass) or here (css)
  • iframe: returns a full HTML page that contains the formatted HTML embedded in a codeblock (Content-Type: text/html)

Full definition of the request body

The api body is defined by the type definition of IApiRequestBody
export type Optional<T> = {
  [prop in keyof T]?: T[prop]
}

interface IFormatRequest extends Optional<IFormatterConfig>
{
  code: string;                       //code to format
}

type IndentationKind = "spaces" | "tabs";

type AlignmentStrategy = "singleline" //align when all aligned nodes are single line. Otherwise do not align (default)
  | "always"                          //always align
  | "never";                          //never align

export interface IFormatterConfig 
{
  lineWidth: number;                                        //(default=100) the number of characters in one line that serves for the formatter as a limit
  indentationLength: number;                                //(default=2) the number of indentation characters used for indentation
  alignPairedLetExpressionsByEqual: AlignmentStrategy;      //(default="singleline") align paired expressions that are children of a let expression by the equal chaaracters
  alignPairedRecordExpressionsByEqual: AlignmentStrategy;   //(default="singleline") align paired expressions that are children of a record expression by the equal character 
  alignLineCommentsToPosition: number;                      //(default=null) align line end comments (starting with "//" and in non empty code lines) to a specific position. Null of no alignment should happen.
  includeComments: boolean;                                 //(default=true) toggle include or exclude comments
  indentSectionMembers: boolean;                            //(default=true) toggle indentation of section members
}

export interface ITextAstSerializerConfig 
{
  ws: string;               //(default: " ") character to use as whitespace
  lineEnd: string;          //(default: "\n") character to use as line break
}

export interface IHtmlAstSerializerConfig {
  ws: string;               //(default: "&nbsp;") character to use as whitespace
  lineEnd: string;          //(default: "<br/>") character to use as line break
  numBrackets: number;      //number of colorized distinct brackets. Brackets can be styled with bracket-{number} css class.
}

export interface ITextFormatRequestBody extends IFormatRequest, Optional<ITextAstSerializerConfig>
{
  resultType: "text";             //return plain text as result
  indentation: IndentationKind;   //indentation "tabs" | "spaces"
}

export interface IHtmlFormatRequestBody extends IFormatRequest, Optional<IHtmlAstSerializerConfig>
{
  resultType: "html"|"codeblock"; //codeblock will return the formatted code structured as a codeblock. Refer to further documentation below to see how you can style it.
  inlineCss: string;              //css that should be inlined into style tags of the html
}

export interface IIFrameFormatRequestBody extends IFormatRequest, Optional<IHtmlAstSerializerConfig>
{
  resultType: "iframe";           //returns a whole html page that contains a styled codeblock containing the formatted code
  theme?: "dark" | "light";       //choose from a dark or light themed styling 
}

export type IApiRequestBody =     //The body is one of the following requests. Basically the "resultType" defines which body is valid.
  IHtmlFormatRequestBody 
  | ITextFormatRequestBody 
  | IIFrameFormatRequestBody; 

Response

If you chose resultType = iframe you will receive a response with Content-Type text/html containing a whole HTML page that can be embedded. All other resultTypes will yield in a json response object that contains the following properties:
  • result (string): The formatted code result (can be text or html string)
  • errors (IApiError[]): An array of errors
  • success (boolean): true when no errors happened. When this is true the errors array is filled. When this is false errors array is null.
Definition of the returned error:
type ApiErrorKind = "UNKNOWN" | "PARSER_ERROR" | "FORMATTER_ERROR" | "SERIALIZATION_ERROR" | "CSS_ERROR" | "INVALID_BODY"
export class ApiError extends Error implements IGenericError {
    kind: ApiErrorKind;  //the kind of error that happened
    innerError: Error;      //inner error if there is one
    meta: any;                 //some meta info if available
    type: string;              //The error type name
    stack: string;             //stacktrace
}

Styling

For all resultTypes but text the formatter applies css classes to the html that you can use to style the formatted html code. You can also provide your style sheet via the inlineCss option (not for resultType = iframe) so the formatter applies the styles to the html using html inline styling. The available css classes are
  • comment
  • constant
    • keyword
    • identifier
      • method-call
    • operator
      • operator-dot
      • operator-keyword
    • bracket
    • bracket-{num}
    • type
  • literal
    • string
    • list
    • boolean
    • number
    • null
    • record
    • string