@api-components/api-request-editor

<api-request-editor>

A web component to render accessible request data editor based on AMF model.

This component implements Material Design styles.

The component creates the UI for editing a HTTP request. It contains:

URL editor
Headers editor
Path/query parameters editor
Payload (body) editor
Authorization editor

See breaking changes and list of required dependencies at the bottom of this document

Version compatibility

This version only works with AMF model version 2 (AMF parser >= 4.0.0). For compatibility with previous model version use 3.x.x version of the component.

Usage

Installation

npm install --save @api-components/api-request-editor

Handling request event

The element do not perform a request. It dispatches api-request custom event with request object on the detail property of the event. The hosting application should handle this event and perform the request. When the response is ready the application should dispatch api-response property with the same id value from the request object. The element clears its state when the event is handled.

AMF model selection

The element handles selected shape computation after selected property is set. The property should be set to AMF supportedOperation node's @id value.

Use api-navigation element to provide the user with accessible navigation through the AMF model.

Override base URI

Sometimes you may need to override APIs base URI. The element provides baseUri property that can be set to replace API's base URI to some other value.

Allowing custom properties

By default the editor only renders form controls to the ones defined in the API spec file. When model for URI/query parameters, headers, or body is not present then the corresponding editor is not rendered. Also, when the editors are rendered there's no option for the user to defined a parameter that is not defined in the API specification.

To allow the user to add custom properties in the editors use allowCustom property. It will force query parameters editor to appear when hidden and the editors renders "add" button in their forms.

Partial model support

Partial model is generated by the AMF service (by MuleSoft) to reduce data transfer size and to reach the performance budget when initializing applications like API Console.

Partial model contains data that are only required to generate view for current API selection.

The element renders the model that is given to it. However, partial model may be missing information about server, protocols, and API version which are required to properly compute URL value.

Note, this can be ignored when setting baseUri as this overrides any API model value.

Pass corresponding model values to server, protocols, and version properties when expecting partial AMF model.

OAuth 2

You need to set redirectUri property to a OAuth 2 redirect popup location. Otherwise authorization won't be initialized.

Validation

The element sets invalid attribute when the editor contains invalid data. You can use it to style the element for invalid input.

When all forms are reported valid but OAuth 2 has no access token value the element still reports it as valid. When the user try to press the send button it will try to force authorization on currently selected authorization panel before making the request.

api-request event

Dispatched when the user requests to send current request.

Properties set on the detail object:

url String The request URL. Can be empty string.
method String HTTP method name. Can be empty.
headers String HTTP headers string. Can be empty.
payload String|File|FormData Message body. Can be undefined.
auth Object Optional, authorization settings from the auth panel.
authType String Name of the authorization methods. One of advanced-rest-client/auth-methods.
id String Generated UUID for the request. Each call of the execute() function regenerates the id.

Use the id property to report the response back with api-response event.

In an html file

<html>
  <head>
    <script type="module">
      import '@api-components/api-request-editor/api-request-editor.js';
    </script>
  </head>
  <body>
    <api-request-editor></api-request-editor>
    <script>
    {
      const editor = document.querySelector('api-request-editor');
      const model = await generateAmfModel();
      editor.amf = model;
      editor.selected = '...'; // a method ID from the AMF model

      editor.addEventListener('api-request', () => {
        // make a request and report the response.
      });
    }
    </script>
  </body>
</html>

In a LitElement

import { LitElement, html } from 'lit-element';
import '@api-components/api-request-editor/api-request-editor.js';

class SampleElement extends PolymerElement {
  render() {
    return html`
    <api-request-editor
      .amf="${this.amf}"
      .selected="${this.selectedAmfId}"
      ?allowCustom="${this.allowCustom}"
      ?allowHideOptional="${this.allowHideOptional}"
      ?allowDisableParams="${this.allowDisableParams}"
      ?narrow="${this.narrow}"
      ?outlined="${this.outlined}"
      ?legacy="${this.legacy}"
      ?readOnly="${this.readOnly}"
      ?disabled="${this.disabled}"
      ?noDocs="${this.noDocs}"
      ?noUrlEditor="${this.noUrlEditor}"
      .redirectUri="${this.redirectUri}"
      @api-request="${this._apiRequestHandler}"></api-request-editor>
    `;
  }

  _apiRequestHandler(e) {
    console.log('current request to run', e.detail);
  }
}
customElements.define('sample-element', SampleElement);

Working with AMF partial model

Only endpoint model with selection set to a method node that is already in the model make sense. Because the model don't have server, protocols, and version definition it has to be computed and set manually.

const elm = document.querySelector('api-request-editor');
const summaryModel = await downloadPartialApiModelSummary();
const endpointModel = await downloadPartialApiModelEndpoint();
elm.amfModel = endpointModel; // This must be set before any computation, it contains `@context` property.
elm.selected = '#123'; // Selected node ID, must be method ID that is in endpoint definition.
elm.server = elm._computeServer(summaryModel); // This is element's inherited method
elm.version = conputeApiVersion(summaryModel); // Compute version from `server` model.
elm.protocols = ['http', 'https']; // This is encoded in AMF model.

Development

git clone https://github.com/advanced-rest-client/api-request-editor
cd api-request-editor
npm install

Running the demo locally

npm start

Running the tests

npm test

API components

This components is a part of API components ecosystem

Breaking Changes in v3

Required dependencies to be included into the app before running this element.

All the dependencies described below are installed with the package.

Code Mirror support

CodeMirror + JSON linter (body editor) + headers hints and syntax (headers editor) + basic syntax (body editor).

<script src="/node_modules/web-animations-js/web-animations-next.min.js"></script>
<!-- dependencies for authorization panel: Digest and Oauth1  -->
<script src="/node_modules/cryptojslib/components/core.js"></script>
<script src="/node_modules/cryptojslib/rollups/sha1.js"></script>
<script src="/node_modules/cryptojslib/components/enc-base64-min.js"></script>
<script src="/node_modules/cryptojslib/rollups/md5.js"></script>
<script src="/node_modules/cryptojslib/rollups/hmac-sha1.js"></script>
<script src="/node_modules/jsrsasign/lib/jsrsasign-rsa-min.js"></script>
<!-- Code mirror -->
<script src="/node_modules/jsonlint/lib/jsonlint.js"></script>
<script src="/node_modules/codemirror/lib/codemirror.js"></script>
<script src="/node_modules/codemirror/addon/mode/loadmode.js"></script>
<script src="/node_modules/codemirror/mode/meta.js"></script>
<script src="/node_modules/codemirror/mode/javascript/javascript.js"></script>
<script src="/node_modules/codemirror/mode/xml/xml.js"></script>
<script src="/node_modules/codemirror/mode/htmlmixed/htmlmixed.js"></script>
<script src="/node_modules/codemirror/addon/lint/lint.js"></script>
<script src="/node_modules/codemirror/addon/lint/json-lint.js"></script>
<link media="all" rel="stylesheet" href="/node_modules/codemirror/addon/lint/lint.css" />

CodeMirror's modes location. May be skipped if all possible modes are already included into the app.

<script>
/* global CodeMirror */
CodeMirror.modeURL = 'node_modules/codemirror/mode/%N/%N.js';
</script>