@api-components/api-url-data-model NPM

<api-url-data-model>

An element to generate view model for api-url-editor and api-url-params-editor elements from AMF json/ld model.

AMF allows to read any API spec document (RAML, OAS by default) and produce common data model.

This component creates a view model used in request forms from selected endpoint or HTTP method.

The component computes all required values from AMF's WebApi model.

const elm = document.querySelector('api-url-data-model');
const model = await downloadApiModel();
elm.amf = model;
elm.selected = '#123'; // Selected node ID, must be method's ID.
elm.server = computeCurrentServer(model, selected);

console.log(elm.apiParameters); // API base path parameters
console.log(elm.endpointUri); // API base path parameters
console.log(elm.apiBaseUri); // Computed value of base URI for the API.
console.log(elm.pathModel); // Endpoint's URI variables (including base URI's variables)
console.log(elm.queryModel); // Method's query parameters

When using partial query model the protocols and version model must be set manually as partial model won't have this information.

After reseting the model to full AMF WebApi model the values are updated.

const elm = document.querySelector('api-url-data-model');
const summaryModel = await downloadPartialApiModelSummary();
const endpointModel = await downloadPartialApiModelEndpoint();
elm.amf = endpointModel;
elm.selected = '#123'; // Selected node ID, must be method ID that is in endpoint definition.
elm.server = elm.computeCurrentServer(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.

console.log(elm.apiParameters); // API base path parameters
console.log(elm.endpointUri); // API base path parameters
console.log(elm.apiBaseUri); // Computed value of base URI for the API.
console.log(elm.pathModel); // Endpoint's URI variables (including base URI's variables)
console.log(elm.queryModel); // Method's query parameters

Overriding API's base URL

To alter URL data model without changing the AMF or API data simply set apiUri proprty. The component then regenrates apiBaseUri and endpointUri to include updated API base uri.

element.apiUri = 'https://proxy.domain.com';

AMF 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.

Breaking changes

OAS 3 - server required

Version 5 of the component supports OAS 3 which can define multiple servers on an operation, endpoint, or the root of the API. Because of that the element does not computes server for current selection. Instead it expect the server object to be passed as a property.

Usage

Installation

npm install --save @api-components/api-url-data-model

In an html file

<html>
  <head>
    <script type="module">
      import '@api-components/api-url-data-model/api-url-data-model.js';
    </script>
  </head>
  <body>
    <api-url-data-model></api-url-data-model>
  </body>
</html>

In a LitElement template

import { LitElement, html } from 'lit-element';
import '@api-components/api-url-data-model/api-url-data-model.js';

class SampleElement extends LitElement {
  render() {
    return html`
    <api-url-data-model
      .amf="${this.amdModel}"
      .selected="${this.selectedShape}"
      @apiparameters-changed="${this._apiBasePramsHandler}"
      @endpointuri-changed="${this._endpointUriHandler}"
      @apibaseuri-changed="${this._apiBaseUriHandler}"
      @pathmodel-changed="${this._pathModelHandler}"
      @querymodel-changed="${this._queryModelHandler}"></api-url-data-model>`;
  }

  _apiBasePramsHandler(e) {
    this.apiParameters = e.target.apiParameters;
  }

  _endpointUriHandler(e) {
    this.endpointUri = e.target.endpointUri;
  }

  _apiBaseUriHandler(e) {
    this.apiBaseUri = e.target.apiBaseUri;
  }

  _pathModelHandler(e) {
    this.pathModel = e.target.pathModel;
  }

  _queryModelHandler(e) {
    this.queryModel = e.target.queryModel;
  }
}
customElements.define('sample-element', SampleElement);

In a Polymer 3 element

import {PolymerElement, html} from '@polymer/polymer';
import '@api-components/api-url-data-model/api-url-data-model.js';

class SampleElement extends PolymerElement {
  static get template() {
    // don't use 2-way data binding as setters do not exists.
    return html`
    <api-url-data-model
      amf="[[amf]]"
      selected="[[selectedShape]]"
      on-apiparameters-changed="_apiBasePramsHandler"
      on-endpointuri-changed="endpointUriHandler"
      on-apibaseuri-changed="_apiBaseUriHandler"
      on-pathmodel-changed="_pathModelHandler"
      on-querymodel-changed="_queryModelHandler"></api-url-data-model>
    `;
  }

  _apiBasePramsHandler(e) {
    this.apiParameters = e.target.apiParameters;
  }

  _endpointUriHandler(e) {
    this.endpointUri = e.target.endpointUri;
  }

  _apiBaseUriHandler(e) {
    this.apiBaseUri = e.target.apiBaseUri;
  }

  _pathModelHandler(e) {
    this.pathModel = e.target.pathModel;
  }

  _queryModelHandler(e) {
    this.queryModel = e.target.queryModel;
  }
}
customElements.define('sample-element', SampleElement);

Known issues

The element does not produce model for unions and arrays for RAML's queryString property. This may be supported in the future.

Development

git clone https://github.com/advanced-rest-client/api-url-data-model
cd api-url-data-model
npm install

Running the demo locally

npm start

Running the tests

npm test

API components

This components is a part of API components ecosystem

amf data-model arc api-components transformer

@api-components/amf-helper-mixin @api-components/api-view-model-transformer lit-element

@infinitebrahmanuniverse/nolb-_api @everything-registry/sub-chunk-73 @zalastax/nolb-_api @api-components/api-request-editor

6 years ago

6 years ago

6 years ago

6 years ago

6 years ago

6 years ago

6 years ago

6 years ago

6 years ago

6 years ago

6 years ago

6 years ago

6 years ago

7 years ago

7 years ago

7 years ago

7 years ago

7 years ago