Understanding Web Services API

nHyNapOba

12 years ago

This document describes the list of SwiftKanban Web services interface definitions that are available for enterprises to integrate with SwiftKanban. We are continuously growing the list of web services based on the requirements expressed by customers and new features being added to the product. So if any web service expected is not found mentioned here, feel free to contact us at support@swiftkanban.com and we are looking at adding those.

Note: You can execute a maximum of up to 50 web services (SOAP or REST) per minute. This number does not include those web services fired by any action in the Story Map or External Work Request.

Read any of the following sections to know more about the web services and get started with them.

SOAP Web Services
REST API Web Services

SOAP Web Services

Platform

The link https://login.swiftkanban.com/axis2/services/KanbanCardService?wsdl opens our WSDL to access card services. These web services can be used on any Operating System and any Web Service client capable of handling SOAP 1.1 or SOAP 1.2 protocol.

Note: The web services are accessible via the public Digite Service Provider Host https://login.swiftkanban.com/axis2

To view the list of functions that can be performed on a card, click Services, and then click KanbanCardService. IT opens the WSDL page where you can access all web services related to the card functions.

Authentication

SwiftKanban Web Service uses username token for authentication. For SwiftKanban Users, they can navigate to the User Profile page and click the Authorization Token on the left panel.

Steps to find your API authorization token:

Login to your SwiftKanban web application.
Click on the profile picture in the upper right corner.
Next, click the user name to open the profile view window.
Now, click the Authorization Token on the Side toolbar at the left to access your authorization token.

For other users, it is a policy-based configuration that follows the WS-Security Policy Language to establish the security requirements of the Web service.

To understand the WS-Security Police, please refer to https://wso2.com/cloud/managed/security-policy/. Specifically, the UsernameToken WS-SecurityPolicy is applied which conveys security credentials through username and password information as part of the WS-Security headers.

Port KanbancardServiceSOAP11port/12port Port type

Location	https://login.swiftkanban.com/axis2/services/KanbanCardService.KanbancardServiceSOAP11port
Protocol	SOAP
Transport protocol	SOAP over HTTP

Provide the header information in the soapenv header section as given below. Moreover, provide the username and password in specific tags.

SOAP 1.1 Protocol <soapenv:Header> <wsse:Security xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd" soapenv:mustUnderstand="1"> <wsu:Timestamp xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd" wsu:Id="Timestamp-12468716">...</wsu:Timestamp> <wsse:UsernameToken xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd" wsu:Id="UsernameToken-31571602"> <wsse:Username>parth@gandiva.com</wsse:Username> <wsse:Password Type="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-username-token-profile-1.0#PasswordText">welcome1</wsse:Password> </wsse:UsernameToken> </wsse:Security> </soapenv:Header>  SOAP 1.2 Protocol <soapenv:Header> <wsse:Security xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd" soapenv:mustUnderstand="1"> <wsse:UsernameToken xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd" wsu:Id="UsernameToken-31571602"> <wsse:Username>parth@gandiva.com</wsse:Username> <wsse:Password Type="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-username-token-profile-1.0#PasswordText">welcome1</wsse:Password> </wsse:UsernameToken> </wsse:Security> </soapenv:Header>

SwiftKanban SOAP Web Service exposes API to allow users to perform common card operations as listed below.

REST API Web Services

You can use SwiftKanban REST APIs as service endpoints to interact with SwiftKanban application remotely and perform various card functions.

Platform

The link https://login.swiftkanban.com/swift-api-doc takes you to the Swagger document to access different services. These web services can be used on any operating system and any web service client capable of handling REST API protocol.

For example, to view the list of operations that can be performed on a card, you can click CardService. It opens the Swagger page where you can access all services related to the card operations.

Authentication

The authentication method for the REST APIs is JWT token-based authentication. In both cases, SwiftKanban REST web service uses JWT based authentication with no expiry of generated JWT token. To access any of the REST web services you must first generate the JWT token using your userId:password. To know more about generating an Authentication Token, see this information.

Integration User

Integration User is one of the primary roles in Swiftkanban who can perform integration-related activities for a particular account and Board. Any integration-related activity needs to be performed through the integration user for better tracking. For example, if you want to add a card to the Board via web service, but don’t have access to the same Board, then you can do the same by using the credentials of the Integration User. The card added will remain assigned the Integration User till it gets reassigned to someone else.

You are assigned one integration user license by default and can have any number of integration users for your SwiftKanban account depending on the assigned license. The password for the integration user is sent to the Account Admin. Moreover, any existing user can be modified to the integration user, but once done, can never be changed back to any other user role.

To find out the credentials of the integration user, you need to log in with your registered account, and then navigate to the People listing to find the user Id of the integration user.

To generate a password for integration user, perform any of the following steps:

Select the integration user row and click the generate password button on the left side toolbar. The App account holder will immediately receive a mail containing credentials of integration user.
On the login page, click the forgot password link and by providing integration user id the App account holder will immediately receive a mail containing credentials of integration user.

Generating Authentication Token

You can authenticate using your personal SwiftKanban id or via the Integration User. To provide the personal access token through an HTTP header, you must first convert the userId:password to a Base64 string. Here is an example.

{

"AuthenticationToken":"SwiftKanban dGVzdHVzZXIxQHRlc3QuY29tOndlbGNvbWVAMQ=="

}

Where dGVzdHVzZXIxQHRlc3QuY29tOndlbGNvbWVAMQ== is Base64Encoded of the user testuser1@test.com and password welcome@1.

Now pass this Authentication Token string as a part of the body to call the TokenService. The resulting output string will be returned in the response body as the AuthorizationToken element, which is one of the several name/value paired objects in a data collection. Make sure that the user for which you are generating personal access token is having enough access to perform the activities. Below is the snippet of the sample call to generate the JWT token.

The following snippet shows the generated JWT authentication token as part of the response body. The response body contains AuthorizationToken element which should be passed as header to call all the SwiftKanban REST web services.

Components of a REST API request/response pair

A REST API request/response pair can be separated into the following components:

The request URI, in the following form:

https://{host:port}/restapi/{parentResource}/{parentResourceId}/{resource}?loginId={userId}

resource path: {parentResource}/{parentResourceId}/{resource}. For example boards/boardId/cards.
After “?” mark, optional parameters can be passed. In the above example, loginId is passed to perform the operations like updateby/addedby/deletedby/closedby on behalf of the particular user.

HTTP request message header fields:

A required HTTP method (also known as an operation), which tells the service what type of operation you are requesting. SwiftKanban REST APIs support GET, PUT, POST and DELETE methods.
Additional header fields, as required by the specified URI and HTTP method. For example, an AuthorizationToken header that provides a bearer token containing client authorization information for the request.

Optional HTTP request message body fields, to support the URI and HTTP operation. For example, POST operations contain MIME-encoded objects that are passed as complex parameters.

For POST or PUT operations, the MIME-encoding type for the body should also be specified in the Content-type request header.

Kanban web service accepts content-type as JSON (application/json)

HTTP response message header fields:

An HTTP status code, ranging from 2xx success codes to 4xx or 5xx error codes.
Optional additional header fields, as required to support the request’s response, such as a Content-type response header.

Optional HTTP response message body fields:

MIME-encoded response objects may be returned in the HTTP response body, such as a response from a GET method that is returning data. Typically, these objects are returned in a structured format such as JSON, as indicated by the Content-type response header. For example, when you request an access token from SwiftKanban, it will be returned in the response body as the AuthorizationToken element, one of several name/value paired objects in a data collection.

SwiftKanban REST Web Service exposes API to allow users to perform common card operations as listed below.

Note: Currently, the multi-select option is available only for the following web services:

Was this helpful?
Yes No