undefined component

Tag: <raml-request-panel>

Installation

Using bower:

bower install --save advanced-rest-client/raml-request-panel

The request panel view for the request defined as a RAML method. It is a main view element for the API console to display the request panel related to the RAML specification.

The element has it's own XHR / Fetch transport method and it will be used if the hostng application do not handle the api-console-request event.

When the user request to make the HTTP request then cancellable api-console-request event will be fired with the request details (see below). The hosting application, if it about to use different transport method, should cancel the event by calling preventDefault() function on the event (and possibly stopPropagation()) and handle the request. If the event was not prevented (canceled) then internall Fetch/XHR will be used.

When the request is ready then the hosting app must fire the api-console-response event with created Request and Response objects. This element listens on the window property for the api-console-response event.

Events

api-console-request

This event is fired when the user request to make a HTTP request. This event will have the following properties set on the detail object:

Property	Type	Description
url	String	The request URL
method	String	The HTTP method
headers	String	Headers to send
payload	String	Payload to send
auth	Object	Optional. For some authorization methodss (like NTLM) the authorization header or query param can't be set and the authorization must be made on the connection. In this cases the auth object will be set with type and settings properties. While type is the name of the authorization method, the settings object depends on the authorization method and may vary. Detailed documentation for the auth methods is in the auth-methods element.

api-console-response

This event must be fired when the hosring app finish the request. It must contains generated Request and Response object according to the Fetch specification.

Becaue the Fetch API is a new API not all browsers support it. In this case the polyfill must be used in the hosted app. Add the fetch-polyfill element (advanced-rest-client/fetch-polyfill) to the hosted app to have the support. It is recommended to use this element so the polyfill will be loaded only once. See the raml-request-panel-simple-xhr element for example implementation.

Property	Type	Description
request	Object	The request object as defined in the Fetch API spec.
response	Object	The response object as defined in the Fetch API spec.
isXhr	Boolean	If not set the element assumes it's true. Indicated if the transport method doesn't support advanced timings and redirects information. See below.
error	Error	When the request / response is errored (request.ok equals false) then the error object should be set with the human readable message that will be displayed to the user.
loadingTime	Number	The response full loading time

See Advanced transport options for more event options.

Example

<raml-request-panel
  method="[[ramlMethod]]"
  redirect-url="http://oauth.redirect.url"
  request="{{request}}"
  response="{{response}}"
  response-error="{{responseError}}"
  loading-time="{{loadingTime}}"></raml-request-panel>

Advanced transport options

The response panel in the ARC elements is able to display the response in simple and advanced view.

Simple is meant to be used when the HTTP request has been made by the simple transports like XHR or Fetch. It just displays the response status, headers and paylaod.

Advanced view is reserved for transport methods that are able to generate additional informations about the request and resposne. This information is timings for the request/response, timings for the redirects and information about redirects.

When the advanced options are set then the isXhr flag on the api-console-response event's detail object must be set to true.

timings

The timings propery added to the api-console-response is the request / response timings as defined in HAR 1.2 spec. For example:

"timings": {
  "blocked": 0,
  "dns": -1,
  "connect": 15,
  "send": 20,
  "wait": 38,
  "receive": 12,
  "ssl": -1,
  "comment": ""
}

If the timings property is set the loadingTime property is optional since it will be calculated from the detailed timing.

redirectTimings

The redirectTimings propery added to the api-console-response is the list of the timings objects as defined in HAR 1.2 specification. The list should be ordered list of redirections. For example:

"redirect-timings": [{
  "blocked": 0,
  "dns": -1,
  "connect": 15,
  "send": 20,
  "wait": 38,
  "receive": 12,
  "ssl": -1,
  "comment": ""
}]

redirects

The redirects property added to the api-console-response event is the list of objects. Each object should have the headers property as a HTTP headers string, status as a HTTP status and optionally statusText. It is consisted with the Response object except the headers are String instead of the Headers object.

"redirects": [Response {
  "status": 301,
  "statusText": "Moved Permanently",
  "headers": "Content-lenght: 0"
}]

sourceMessage

The HTTP source message sent to the server. It should be full message from the message header to the request body.

Advanced event example

var event = new CustomEvent('api-console-response', {
  cancelable: true,
  bubbles: true,
  composed: true,
  detail: {
    isXhr: true,
    request: request,
    response: response,
    error: new Error('Dummy error'), // Has the response details so it shouldn't be set.
    loadingTime: 125, // This is optional because timings is set
    timings: { dns: 123, ... }
    redirectTimings: [{ dns: 123, ... }],
    redirects: [redirectResponse1, ...],
    sourceMessage: 'HTTP/1.1 200 OK\n ....'
  }
});
document.body.dispatchEvent(event);

Styling

<raml-request-panel> provides the following custom properties and mixins for styling:

Custom property	Description	Default
--raml-request-panel	Mixin applied to the element	{}
--raml-request-panel-panel-border-color	Border color of each block in the tabs	rgba(0, 0, 0, 0.24)
--raml-request-panel-container	Mixin applied to the main content container	{}
--raml-request-panel-container-narrow	Mixin applied to the main content container when layout is narrow	{}
--action-button	Mixin applied to the action button	{}
--action-button-hover	Mixin applied to :hover state for the action button	{}
--action-button-disabled	Mixin applied to disbaled action button	{}
--primary-color	background-color of the main action button	--primary-color
--primary-action-color	Color of the main action button	--primary-action-color
--action-accent-button-disabled-color	Color of disabled action button	``
--primary-button-background-color	Background color of the primary button.	--accent-color
--primary-button-color	Font color of the primary button	#fff
--primary-button-hover-background-color	Background color of the primary button when hovered.	--accent-color
--primary-button-hover-color	Font color of the primary button when hovered.	#fff

You can set the narrow property so the element will be rendered in the mobile view. This property will be propagated to all sub-elements that uses this property to change layout.

API

Component properties (attributes)

method

• Type: Object A RAML node representing a method node in RAML definition. It should be obtained from the raml-path-to-object element.

selectedTab

• Type: number
• Default: 0 Selected request tab.

contentType

• Type: string Current content type.

isPayloadRequest

• Type: boolean
• Default: false
• Read only property Computed value if the method can carry a payload

headers

• Type: string Headers for the request.

payload

• Type: string Body for the request

url

• Type: string Current URL

narrow

• Type: boolean If set it will renders the view in the narrow layout.

narrowWidth

• Type: string
• Default: "768px" A widith below which the narrow property will be set to true.

loadingRequest

• Type: boolean
• Default: false
• Read only property If true then the request is currently loaded.

responseIsXhr

• Type: boolean
• Read only property If true then the request was made using the XHR object (it has less data in the response).

request

• Type: Request
• Read only property The request object created by the transport. It should be the Request object as defined in the Fetch API spec. This element provides the polyfill for this API.

response

• Type: Response
• Read only property The response object from the transport. It should be the Response object as defined in the Fetch API spec. This element provides the polyfill for this API.

responseError

• Type: Object
• Read only property Set when the response errored.

loadingTime

• Type: number
• Read only property Response full loading time.

timings

• Type: Object
• Read only property If the transport method is able to collect detailed information about request timings then this value will be set. It's the timings property from the HAR 1.2 spec.

redirectTimings

• Type: Array
• Read only property If the transport method is able to collect detailed information about redirects timings then this value will be set. It's a list of timings property from the HAR 1.2 spec.

redirects

• Type: Array
• Read only property It will be set if the transport method can generate information about redirections.

sourceMessage

• Type: string
• Read only property Http message sent to the server.

This information should be available only in case of advanced HTTP transport.

authRequired

• Type: boolean Received from the authorization panel state if authorization is required

authValid

• Type: boolean Received from the authorization panel state if authorization data is valid

redirectUrl

• Type: string OAuth2 redirect URL

authMethod

• Type: string Selected by the user auth method (if any)

authSettings

• Type: Object Current authorization settings.

urlInvalid

• Type: boolean Computed value when the URL change. If not valid form submission won't be possible.

noUrlEditor

• Type: boolean Hides the URL editor from the view. The editor is still in the DOM and the urlInvalid property still will be set.

baseUri

• Type: string A base URI for the API. To be set if RAML spec is missing baseUri declaration and this produces invalid URL input. This information is passed to the URL editor that prefixes the URL with baseUri value if passed URL is a relative URL.

queryModel

• Type: Object Computed model for query parameters

uriModel

• Type: Object Computed model for URI parameters

hasUriParameters

• Type: boolean Computed value from the parameters model

hasQueryParameters

• Type: boolean Computed value from the parameters model

hasParameters

• Type: boolean Computed value from the parameters model

noAuth

• Type: boolean
• Default: true
• Read only property Value computed when RAML method change. It is set to true when authorization is not defined for current endpoint's method.

Component methods

execute

• Return type: undefined Execute the request with current settings. This method fires the api-console-request so the request can be handled by the hosting app. Hosting app must call event.preventDefault() on the event otherwise the console will attempt to make a request usnig XHR object.

authAndExecute

• Return type: undefined Performs an authorization by bringing up the authorization form in a popup and after successful authorization executes the request.

serializeRequest

• Return type: undefined Returns an object with the request properties. The object contains:
• method (String)
• url (String)
• headers (String)
• payload (String)
• auth (Object)

The auth property is optional and is only added to the request if simple authorization header will not work. For example NTLM auth method has to be made on a single socket connection (authorization and the request) so it can't be made before the request.

The auth object contains 2 properties:

• type (String) the authorization type - one of from the auth-methods element
• settings (Object) Authorization parameters entered by the user. It vary and depends on selected auth method. For example in case of the NTLM it will be: username, password and domain.

undefined component

Tag: <raml-request-panel-simple-xhr>

Installation

Using bower:

bower install --save advanced-rest-client/raml-request-panel-simple-xhr

The raml-request-panel-simple-xhr is an element that executes the request if the hosted app do not handle the api-console-request event.

It can be used as a boilerplate for communication with the raml-request-panel element to handle request event, execute the request and return the result.

The raml-request-panel is based on the fetch's API Request and Response object. The returning event transport them to the source element. Because the Response object is not intended to carry a custom errors, in case of error, the Response object only carrying nformation response.ok equals false and the error Error object is added to the event's detail object.

This element don't listen for the api-console-request event giving a chance for the hosted app to handle it. If the hosted app intend to handle the requests it should listen for an event:

window.addEventListener('api-console-request', function(e) {
  var data = e.detail;
  console.log(data.url);
  console.log(data.method);
  console.log(data.payload);
  console.log(data.headers);
  console.log(data.auth); // optional, see `raml-request-panel.serializeRequest()`
});

After the request is made (successfully or not) the api-console-response event must be fired. It should have request and response objects added to the event's detail object. If the request is errored the it must contain additional error proeprty which is JS' Error object with the human readable message (it will be displayed as an error message). Additionaly the detail object can contain the isXhr property which is set to true be default. It should be set to false if the request has been made by more than XHR advanced transport which dives information about timings and redirects.

See the response-panel for more information.

var event = new CustomEvent('api-console-request', {
  cancelable: false,
  bubbles: true,
  composed: true,
  detail: {
    request: new Request(...),
    response: new Response(body, {status: 200})
  }
});
this.dispatchEvent(event);

Becaue the Fetch API is a new API not all browsers support it. Therefore the polyfill must be used in the hosted app. Add the fetch-polyfill element (advanced-rest-client/fetch-polyfill) to the hosted app to have it supported.

Because this element fires back an event it has to be attached to the DOM.

API

Component properties (attributes)

loading

• Type: boolean
• Default: false
• Read only property If true then the request is currently loaded.

request

• Type: Object Generated Request object during the latest request

response

• Type: Object Generated Response object during the latest request

error

• Type: Object Generated error object during the latest request

loadingTime

• Type: number Total request / response time

Component methods

execute

• Return type: undefined Executes the request.