A web component to render accessible request data editor based on AMF model.
This component implements Material Design styles.
The component contains an UI for editing a HTTP request. It contains:
- URL editor
- Headers editor
- Path/query parameters editor
- Payload (body) editor
- Authorization editor
This component has been moved to api-request
. Use the other one instead.
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.
npm install -S @api-components/api-request-editor
The element do not perform a request by its own. It dispatches api-request
custom event with the 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.
You can use @advanced-rest-client/xhr-simple-request
element to add required logic. However, it does not deal with CORS issues.
Note, if eventsTarget
property is set, the corresponding events have to be handled at most at this node. It means if the eventsTarget
is set to a node but the api-response
event is dispatched on body
or the window
then the component won't handle this event.
Set selected
property to the value of an AMF's @id
property for supportedOperation
shape. This initializes the component to generate the view for current HTTP method.
The amf
property also has to be set in order to compute required properties like AMF keys in compact model or server definition.
Use api-navigation element to provide the user with accessible navigation through the AMF model.
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.
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 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.
You need to set redirectUri
property to the OAuth 2 redirect popup location. Otherwise authorization won't be initialized.
Most authorization methods are working out of the box and are applied to the request when the send function is called. However there are some required dependencies for OAuth 1 that are not included in this element, and special case for Digest authorization method.
Because OAuth 1 is rather rare and obsolete authorization method, this component won't include required dependencies. If in your use case you require using OAuth 1 method then include the following libraries into your application before authorization is triggered.
<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>
The cryptojslib
is already installed with this module as this is a required dependency.
Digest authorization method operates directly on the connection by responding to a challenge requested by the server. This requires a series of request - response sent over the same socket. Web platform has no tools to do this programmatically (XHR and Fetch does not allow to directly interact with the socket). Because of that, when the server requires Digest authentication the browser take control over this process and will ask the user for credentials.
The auth
array may contain digest
type authorization, if such is defined by the API. This should be used in cases where the request is passed through a proxy or send to a mocking service to generate appropriate request message.
const digest = (request.auth || []).find((item) => item.type === 'digest');
if (digest.valid) {
const { settings } = digest;
// settings has user provided information
}
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.
<style>
api-request-editor[invalid] {
border: 1px red solid;
}
</style>
<api-request-editor></api-request-editor>
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
Array<Object>
Optional, authorization settings from the authorization panel. - id
String
Generated UUID for the request. Each call of theexecute()
function regenerates theid
.
Use the id
property to report the response back with api-response
event.
<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>
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}"
?compatibility="${this.compatibility}"
?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);
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.amf = 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.
git clone https://github.com/advanced-rest-client/api-request-editor
cd api-request-editor
npm install
npm start
npm test
This components is a part of API components ecosystem
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>