Skip to content

wmaop API

Jump to bottom
Richard Tomlinson edited this page Nov 5, 2016 · 14 revisions

wm-aop restful api

Overview

wm-aop RESTful API provides the ability to define mocks within webMethods Integration Server. Note that where paths are shown, they should be prepended with the base path, eg, when looking at /define/advice the actual path you call is /rest/org/wmaop/define/advice Being familiar with wm-jbehave stories helps to identify use cases and ways to use the API. Note that the examples show responses when the Accept: header is set with text/xml. Setting with application/json is similarly valid where suitable for your tooling. Without the Accept: header you may receive a default response of html. This documentation is auto-generated from the Swagger definition of the API

Version information

Version : 1.1.1

Contact information

Contact : wmaop support
Contact Email : info@wmaop.org

URI scheme

Host : localhost:5555
BasePath : /rest/org/wmaop
Schemes : HTTP

Paths

Get advice details

GET /define/advice/{adviceId}

Description

Specify the adviceId to see details of that advice or leave the adviceId null for all registered advices. Returned values is an IData record structure.

Example

If we register a simple mock, such as that shown in define fixedResponse, then with

GET http://localhost:5555/rest/org/wmaop/define/advice/myMockingId

we receive the response of:

<?xml version="1.0" encoding="UTF-8"?>
<Values version="2.0">
    <value name="id">myMockingId</value>
    <value name="$resourceID">myMockingId</value>
    <record name="advice" javaclass="com.wm.util.Values">
        <record name="myMockingId" javaclass="com.wm.util.Values">
            <value name="adviceId">myMockingId</value>
            <value name="remit">SessionScope[5cf64a1073db108abcec86e8b9b84830]</value>
            <record name="pointcut" javaclass="com.wm.util.Values">
                <record name="flowPositionMatcher" javaclass="com.wm.util.Values">
                    <value name="id">pub.jms:send</value>
                    <value name="type">FlowPositionMatcher</value>
                    <value name="serviceName">pub.jms:send</value>
                </record>
                <value name="interceptPoint">INVOKE</value>
                <record name="pipelineMatcher" javaclass="com.wm.util.Values">
                    <value name="id">pub.jms:send</value>
                    <value name="type">AlwaysTrueMatcher</value>
                </record>
            </record>
            <record name="interceptor" javaclass="com.wm.util.Values">
                <record name="response0" javaclass="com.wm.util.Values">
                    <value name="fileName">mypipeline.xml</value>
                    <record name="JMSMessage" javaclass="com.wm.util.Values">
                        <record name="header" javaclass="com.wm.util.Values">
                            <value name="JMSCorrelationID">ABC123</value>
                        </record>
                    </record>
                </record>
                <number name="invokeCount" type="Integer">0</number>
                <value name="name">CannedResponse:</value>
                <value name="type">CannedResponseInterceptor</value>
                <value name="responseSequence">SEQUENTIAL</value>
            </record>
            <value name="state">ENABLED</value>
        </record>
    </record>
</Values>

Parameters

Type Name Description Schema Default
Path adviceId
required 		Id of the advice. Applies to any form of advice: scenario; exception; fixedResponse; assertion. string

Responses

HTTP Code Description Schema
200 IData structure of advices. No Content

Delete an advice

DELETE /define/advice/{adviceId}

Description

Delete an advice, reverting back to standard behaviour for that service."

Example

Deleting an advice with the id of myMockingId

DELETE http://localhost:5555/rest/org/wmaop/define/advice/myMockingId

Parameters

Type Name Description Schema Default
Path adviceId
required 		Id of the advice. Applies to any form of advice: scenario; exception; fixedResponse; assertion. The adviceId is mandatory otherwise no delete occurs. string

Responses

HTTP Code Description Schema
200 200 Returned in all cases even when no advice exists for the id No Content

Create an assertion

POST /define/assertion/{adviceId}

Description

Firing mocks and testing pipeline values might be enough to satisfy you that the test has worked, but sometimes its useful to know that a particular service has been invoked and how many times (Eg, if the service has iterated some data, did it action the correct number?). Its also useful to know if a service has produced the expected output but it might not be possible to check the eventual pipeline contents due to values being dropped, etc.

Using Assertions allows you to 'peek' at the pipeline and check that something has happend. Just like mocks, assertions can have conditions applied to them so that the assertion only registers as invoked if the condition is met.

Note that you only need assertions when checking flow through a service, usually before or after a particular service of interest is invoked. If you want to check that your mocks have fired, use a GET /define/assertion/{adviceId} on a mock for a summary of its invokation count

Example

Creating an assertion called postAddingNumbersAssertion which is invoked after the serviceName of _pub.math:addInts is called and the pipeline condition is that the value in the pipeline is 9. Note that the URL is fully URL encoded to escape the spaces, colons and equals symbols. Failure to correctly encode the URL will lead to incorrect behaviour.

POST http://localhost:5555/rest/org/wmaop/define/assertion/postAddingNumbersAssertion?serviceName=pub.math%3AaddInts&condition=value%20%3D%3D%209&interceptPoint=AFTER

Parameters

Type Name Description Schema Default
Path adviceId
required 		The ID of the assertion which also forms its adviceId string
Query condition
optional 		A JEXL pipeline expression to test whether this assertion is applicable. See Pipeline Expressions Using JEXL for details on how to define the expressions. string
Query interceptPoint
required 		The point of interception and either before, invoke or after (Case insensitive). Assertions are generally set either before or after a service. Setting to invoke will replace the service with the assertion, effectively eliminating the original service and having no effect on the pipeline. string
Query scope
optional 		The scope to which this assertion applies and can be either session, user or global (Case insensitive) string "user"
Query serviceName
required 		Fully qualified name of the service which this assertion will interact with string
Query username
optional 		When the scope is user the username to which this applies. If not supplied then the user is assumed to be the authenticated user making the call. string "Username that authenticated the request"

Responses

HTTP Code Description Schema
200 Status 200 No Content

Get simplified details of an assertion (Or indeed any advice...)

GET /define/assertion/{adviceId}

Description

Retrieves simplified details of the assertion to allow easy check of the number of times the assertion was invoked when its condition matched (Ie, pipeline state matched the condition applied or pure invokation count where no condition occurs).

The assertion (And mock) lookup uses the adviceId as a prefix rather than an exact match. This allows a combined count for mocks or assertions where they begin with the id. So, mocks with adviceId's of adviceMock1 and adviceMock2 count have their counts tallied by looking up adviceMock. For example, you may have one of multiple services called, checking the prefix allows a single test to for an invoke count of 1 to prove that one was invoked.

Example

Making a request for the assertion name of myMockingId:

GET http://localhost:5555/rest/org/wmaop/define/assertion/myAssertion

Gives the response of:

<?xml version="1.0" encoding="UTF-8"?>
<Values version="2.0">
    <value name="adviceId">myAssertion</value>
    <number name="invokeCount" type="Integer">0</number>
</Values>

Note that all registered advices are assertable and as such you can specify any {adviceId} to retrieve its invoke count, e.g. GET http://localhost:5555/rest/org/wmaop/define/assertion/myMockingId to see an invoke count of the simple mock defined elsewhere here.

Parameters

Type Name Description Schema Default
Path adviceId
required 		The ID of the assertion or any other advice string

Responses

HTTP Code Description Schema
200 A response indicating the invoke count Assertion Response

Delete an assertion

DELETE /define/assertion/{adviceId}

Description

Delete an assertion by using its adviceId.

Example

DELETE http://localhost:5555/rest/org/wmaop/define/assertion/myMockingId

Parameters

Type Name Description Schema Default
Path adviceId
required 		The ID of the assertion string

Responses

HTTP Code Description Schema
200 Status 200 returned in all cases even when adviceId doesnt exist No Content

Create an exception

POST /define/exception/{adviceId}

Description

Testing of behaviour should include negative paths where exceptional circumstances need handling and exeception handling requires execution. Instead of a service executing, its possible to raise an exception instead thereby simulating a failure.

Exceptions defined this way are assertable and so can be checked to verify they've been invoked using GET /define/assertion/{assertionId}

Example

Preventing the pub.jms:send service from opperating instead an java.lang.UnsupportedOperationException is thrown. In this example, no scope is supplied so the effect is global across IS.

POST http://localhost:5555/rest/org/wmaop/define/exception/myExceptionId?serviceName=pub.jms%3Asend&interceptPoint=invoke&exception=java.lang.UnsupportedOperationException

Parameters

Type Name Description Schema Default
Path adviceId
required 		The ID of the exception string
Query condition
optional 		A JEXL pipeline expression to test whether this assertion is applicable. Useful to raise an exception instead of the service on a particular pipeline state or to raise an exception after as service is called, etc. See Pipeline Expressions Using JEXL for details on how to define the expressions. string
Query exception
required 		The full classname of the exception to raise, such as java.lang.RuntimeException or com.wm.app.b2b.server.ServiceException. The exception class name must be any java class that is Throwable and have a String constructor (Ie one where the exception message is passed in; This is the norm for most exceptions) string
Query interceptPoint
required 		The point to raise the exception and either before, invoke or after (Case insensitive). Setting to invoke will replace the service and trigger an exception instead of the service behaviour. string
Query scope
optional 		The scope to which this mock applies and can be either session, user or global (Case insensitive) string "user"
Query serviceName
required 		Fully qualified name of the service which this exception will interact with string
Query username
optional 		When the scope is user the username to which this applies. If not supplied then the user is assumed to be the authenticated user making the call. string "Username that authenticated the request"

Responses

HTTP Code Description Schema
200 Status 200 in all cases No Content

Delete an exception

DELETE /define/exception/{adviceId}

Description

Delete an exception by its adviceId

Example

DELETE http://localhost:5555/rest/org/wmaop/define/exception/myExceptionId

Parameters

Type Name Description Schema Default
Path adviceId
required 		The adviceId used to register the exception string

Responses

HTTP Code Description Schema
200 Status 200 in all cases No Content

Create a fixed response mock

POST /define/fixedResponse/{adviceId}

Description

Create a mock of a service to return a value in place of that service.

Example

Override the pub.math:addInts service with a mock which has an assertionId of fixedValue always returns a value of 10.

POST http://localhost:5555/rest/org/wmaop/define/fixedResponse/fixedValueMock?serviceName=pub.math%3AaddInts&interceptPoint=invoke

With a body of:

<IDataXMLCoder version="1.0">
  <record javaclass="com.wm.data.ISMemDataImpl">
    <value name="value">10</value>
  </record>
</IDataXMLCoder>

Parameters

Type Name Description Schema Default
Path adviceId
required 		The ID of the assertion which also forms its adviceId string
Query calledBy
optional 		Only invoked if this parameter matches or prefixes one of the services in the call stack. Works in combination with condition or on its own and can ensure mock only works when called from a package (Eg pub.foo) or specific service (Eg pub.foo:bar) string
Query condition
optional 		A JEXL pipeline expression to test whether this assertion is applicable. See Pipeline Expressions Using JEXL for details on how to define the expressions. string
Query interceptPoint
required 		The point of interception and either before, invoke or after (Case insensitive). Mocks are generally set to invoke to replace the service with other behaviour. Its also possible to use with before or after to insert or overwrite values in the pipeline to modify behaviour. string
Query scope
optional 		The scope to which this mock applies and can be either session, user or global (Case insensitive) string "user"
Query serviceName
required 		Fully qualified name of the service which this mock will interact with string
Query username
optional 		When the scope is user the username to which this applies. If not supplied then the user is assumed to be the authenticated user making the call. string "Username that authenticated the request"
Body body
required 		IData which is used to set the pipeline when this mock is executed idata

Responses

HTTP Code Description Schema
200 Status 200 in all cases No Content

Delete a fixed response mock

DELETE /define/fixedResponse/{adviceId}

Description

Delete a fixed response mock using its adviceId.

Example

Delete the mock named fixedValueMock from the create example:

DELETE http://localhost:5555/rest/org/wmaop/define/fixedResponse/fixedValueMock

Parameters

Type Name Description Schema Default
Path adviceId
required 		The ID of the fixed response mock string

Responses

HTTP Code Description Schema
200 Status 200 in all cases No Content

Create a scenario

POST /define/scenario

Description

Create a scenario mock using the as the adviceId.

For full information see the wiki page to create behavioural driven scenario mocks

Parameters

Type Name Description Schema Default
Body body
required 		Scenario XML as defined in wiki idata

Responses

HTTP Code Description Schema
200 Status 200 in all cases No Content

Create a scenario

POST /define/scenario/{adviceId}

Description

Sometimes, simplistic mocks are not sufficient and more complex mock behaviour is required. Creation of a scenario mock allows the definition of conditions on when to trigger the mock and the type of response required. The structure is such that different outputs from the mock can occur based on pipeline values and the sequence of data returned can be varied.

For full information see the wiki page to create behavioural driven scenario mocks

Example

Create a simple scenario mock with the adviceId of mockJmsSendTwoAlternatives to replace pub.jms:send such that calling it returns two alternate responses each time the service is invoked

POST http://localhost:5555/rest/org/wmaop/define/scenario
<scenario xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:noNamespaceSchemaLocation="../../../main/xsd/bddSchema.xsd" id="mockJmsSendTwoAlternatives">
    <given>
        <service intercepted="invoke">pub.jms:send</service>
    </given>
    <when id="sendingJmsMessage">
        <then dispatch="sequential">
          <return><![CDATA[<IDataXMLCoder version="1.0">
            <record javaclass="com.wm.data.ISMemDataImpl">
              <value name="fileName">mypipeline.xml</value>
              <record name="JMSMessage" javaclass="com.wm.data.ISMemDataImpl">
                <record name="header" javaclass="com.wm.data.ISMemDataImpl">
                  <value name="JMSCorrelationID">ABC123</value>
                </record>
              </record>
            </record>
            </IDataXMLCoder>]]>
          </return>
          <return><![CDATA[<IDataXMLCoder version="1.0">
            <record javaclass="com.wm.data.ISMemDataImpl">
              <value name="fileName">mypipeline.xml</value>
              <record name="JMSMessage" javaclass="com.wm.data.ISMemDataImpl">
                <record name="header" javaclass="com.wm.data.ISMemDataImpl">
                  <value name="JMSCorrelationID">DEF456</value>
                </record>
              </record>
            </record>
            </IDataXMLCoder>]]>
          </return>
        </then>
    </when>
</scenario>

Parameters

Type Name Description Schema Default
Path adviceId
required 		adviceId of the scenario. When present, overrides the value in the otherwise the id in the scenario is used as the adviceId string
Body body
required 		Scenario XML as defined in wiki string

Responses

HTTP Code Description Schema
200 Status 200 in all cases No Content

Delete a scenario

DELETE /define/scenario/{adviceId}

Description

Delete a scenario mock

Example

Delete the scenario named mockJmsSendTwoAlternatives from the create example:

DELETE http://localhost:5555/rest/org/wmaop/define/scenario/mockJmsSendTwoAlternatives

Parameters

Type Name Description Schema Default
Path adviceId
required 		using its id, either the adviceId supplied when creating or if not present then the string

Responses

HTTP Code Description Schema
200 Status 200 in all cases No Content

Reset the mocking framework based on scope

GET /reset

Description

Reset the framework, bulk removing advice's (Mocks, assertions, scenarios) within that scope. Calling with a scope of:

  • No scope defined - Calling without the scope specified removes advice's registered as user scope for the user making the call and session scoped, again for the current user making the call only - global scoped advice and those for other users (Ie set as session and user) are left intact. Applicable when running tests in a shared server.
  • ALL - removes all mocks, irrespective of original scope and sets the framework to DISABLED - Effectively disabling it from the runtime.
  • SESSION - removes advice for the current http session
  • USER - removes advice for the current user that's making the call (Eg, you make the call authenticating as Administrator and all advice registered as user scope for Administrator will be removed. Applicable on a shared server where each user is interacting with their own user
  • GLOBAL - removes advice registered as a global scope

Parameters

Type Name Description Schema Default
Query scope
optional 		Scope defines the limit to what is reset. Specifying a scope of ALL resets all scopes and stubs string "No defined scope so removes user and session scoped advice"

Responses

HTTP Code Description Schema
200 Status 200 in all cases No Content

Set the state of the framework

POST /state

Description

Used to enable or disable the framework. Note this doesnt reset any advice so can be used to switch off mocking, verify behaviour and switch mocking back on without having to redefine the mocks.

Initial state on starting the server is disabled. Registering an advice automatically sets the state to enabled.

Note for convenience, the enabled parameter can also be supplied on the GET so that its easy to enable/disable from a browser, etc.

Example

Enable the framework.

POST http://localhost:5555/rest/org/wmaop/state?enabled=true

Parameters

Type Name Description Schema Default
Query enabled
required 		true or false to enable or disable the framework string

Responses

HTTP Code Description Schema
200 Status 200 in all cases status

Get the state of the framework

GET /state

Description

Returns state of the framework to show if its operational.

Example

Newly started server with no mocks defined shows the state as disabled.

GET http://localhost:5555/rest/org/wmaop/state

Return a value of:

<?xml version="1.0" encoding="UTF-8"?>
<Values version="2.0">
  <value name="enabled">false</value>
</Values>

Responses

HTTP Code Description Schema
200 Status 200 in all cases enabled

Test the framework is operational

GET /verify

Description

Used after initial installation or to check if the framework is installed and functioning correctly.

Example

GET http://localhost:5555/rest/org/wmaop/verify

Returns a status indicating it is:

<?xml version="1.0" encoding="UTF-8"?>
<Values version="2.0">
  <value name="status">Mocking framework operational</value>
</Values>

Responses

HTTP Code Description Schema
200 Status 200 status

Produces

  • application/json
  • text/xml

Definitions

Assertion Response

Name Description Schema
adviceId
optional 		ID of the assertion or other advice string
invokeCount
optional 		Number of times this assertion or advice was invoked integer(int32)

enabled

Name Description Schema
status
optional 		Returns 'true' is mocking framework is enabled and operational otherwise 'false' indicating it is switched off and not intercepting calls. string

idata

Name Description Schema
status
optional 		IData used to modify the pipeline string

status

Name Description Schema
status
required 		Should show 'Mocking framework operational' if everything is ok string
Clone this wiki locally