webMethods API Portal tutorial
User onboarding is the process by which you onboard external application developers on to your system. You can define a user onboarding strategy in one of the three ways:
- User registration through email confirmation
- User registration through an approval by a configured approver group/user.
- Automatic user registration
Often times customers would like to integrate user onboarding process within API Portal to be dependent on a approval from a external system. We have provided an option to suspend onboarding process until we get a positive signal from a third party system. Offcourse enabling of 3rd party approval is disabled by default.
If you would like to suspend user onboarding until its officially approved by an external system, you can enable the option "enable 3rd party approval" in configuration settings.
Step1 - Enable 3rd party approval:
Login as admin user and navigate to AdminSettings view and enable the 3rd party approval in the configurations view.
Step 2 - Choose your onboarding strategy:
You can integrate 3rd party approval along with any of above onboarding strategy. For example you can choose email verification from API Portal system first and then go for the 3rd party approval system. In such a case, the authenticity of the email of the registered user will be verified by API Portal and then a USERSIGNUP event will be forked in the system.
With this two steps now we have enabled the 3rd party approval with in API Portal. After this configuration, user who is signing up with API Portal, will not be able to login unless they are approved by external system.
Integrating external approval system using Events API
Once the 3rd party approval is enabled, whenever there is a user register himself with API Portal, a USER_SIGNUP event will be forked in API Portal and will be persisted. A 3rd party approval system can query these events periodically and process them.
Overall flow
below diagram depicts overal interaction flow between API Portal and external approval system.
Querying events API for signup events
| curl --request GET \ --url 'https://api.portal.com/abs/apirepository/v1/events?eventStatus=NEW&eventType=USER_SIGNUP&duration=24h' \ --header 'authorization: Basic c3lzdGVtOm1hbmFnZXI=' \ --cookie routing.umc=.umc0000000001 |
For example above request will fetch USER_SIGNUP events with event status being in NEW and forked in last 24h.
Payload
Rest interface will produce a collection of signup events as shown below
| [ { "executor":{ "firstname":"user1", "name":"user1@test.com", "lastname":"user1", "email":"user1@test.com", "id":"eb7c8c77-91f4-34c7-8dd7-12635277a1f2" }, "source":{ "id":"30d19581-6425-11e9-6162-0a46608af41e" }, "contextdata":{ "id":"eb7c8c77-91f4-34c7-8dd7-12635277a1f2", "firstName":"user1", "lastName":"user1", "email":"user1@test.com" }, "type":"USER_SIGNUP", "eventid":"30fb64a1-6425-11e9-6162-0a46608af41e", "status":"NEW", "creationdate":"2019-04-21 11:04:10" } ] |
The complete set of user entered data will be placed in the context data. External system querying this API will have access to the complete form fields in the signup form.
Acknowledging the events from 3rd party:
Once the events are queried from API Portal, inorder to be able to API Portal to know these events are being processed by external system, the events can be acknowledged to API Portal using below REST API
|
curl --request POST \
--url https://api.portal.com/abs/apirepository/v1/events \
--header 'authorization: Basic c3lzdGVtOm1hbmFnZXI=' \
--header 'content-type: application/json' \
--data '[
{
"eventid":"30fb64a1-6425-11e9-6162-0a46608af41e",
"status": "ACCEPTED"
}
]'
|
You can use single REST invocation to acknowledge a chunk of events. Event ids in the acknowledgement payload can be derived from the event id that we received in the query API.
Once we acknowledge, if we query the events API again, we can notice that events are marked now with eventStatus being INPROGRESS. These events will no longer be provided when we query for events with eventstaus as NEW.
Acknowledging the result of approval:
INPROGRESS events can either be approved / rejected based on the decision made in external approval system.
To approve:
|
curl --request POST \
--url https://api.portal.com/abs/apirepository/v1/events \
--header 'authorization: Basic c3lzdGVtOm1hbmFnZXI=' \
--header 'content-type: application/json' \
--data '[
{
"eventid":"30fb64a1-6425-11e9-6162-0a46608af41e",
"status": "ACCEPTED"
}
]'
|
To reject:
|
curl --request POST \
--url https://api.portal.com/abs/apirepository/v1/events \
--header 'authorization: Basic c3lzdGVtOm1hbmFnZXI=' \
--header 'content-type: application/json' \
--data '[
{
"eventid":"30fb64a1-6425-11e9-6162-0a46608af41e",
"status": "REJECTED"
}
]'
|