Business Bot Platform REST API¶
The Business Bot Platform API is a RESTful API and provides programmatic
access to entities of the Business Bot Platform and lets you easily
integrate the Business Bot Platform with 3rd party tools. The API
supports JSON for requests and responses. The response content type is
requested via the HTTP Accept header (application/json
). All resources are
accessible via https and are located at https://my.bbp.local/bbp/rest/api/1.0/
for
public cloud and https://<TenantId>.bbp.local/bbp/rest/api/1.0/
for private cloud.
Authentication¶
The REST API accepts authentication using Tenant Id
, API Id
and API Key
. By default, the client must
authenticate to access all resources. The Tenant Id
corresponds to the organization id, which corresponds to the
subdomain of the bbp.local URL (for example, if your Business Bot platform
URL is mycompany.bbp.local
, the organization Id would be mycompany
). If
you do not specify the Tenant Id
, the authentication will fail.
Exception Handling (Errors)¶
The Business Bot Platform uses HTTP status code in the response to
report the success or failure of an API request. Codes in the 1xx
range
are intended for informational purposes. Codes in 2xx
range show
success, codes in 3xx
range are reserved for redirections, codes in 4xx
range show client errors (for example a missing parameter), and codes in
5xx
range indicate errors on the server side. In case of an error, the
response contains the following information (e.g.,
{\"code\":402,\"description\":\"Unknown source user\",\"status\":\"false\"}
):
Attribute | Description |
---|---|
code | The corresponsing HTTP status code |
description | A human readable description of the error |
status | General success status of the request |
The following overview shows the most important error codes:
Code | Description |
---|---|
1xx - Informational | |
2xx - Success | |
200 | OK |
3xx - Redirection | |
4xx - Client Error | |
401 | Unauthorized |
402 | Unknown source user |
403 | Unknown target user |
405 | Method not allowed |
410 | Unknown system type and system release |
450 | API user or API key invalid |
451 | API user inactive |
452 | API user has no license |
453 | API user license is expired |
454 | API user has exceeded the total number of messages per month |
455 | Queue name does not exists |
456 | System identifier does not exists |
457 | API user has limited license but requires enterprise license |
5xx - Server Error | |
500 | Internal processing error |
503 | The server is currently unavailable because of maintenance |
API Versioning¶
We will release a new version of the API when we make backwards-incompatible changes. We consider the following changes to be backwards-compatible:
- Adding new API resources.
- Adding new optional request parameters to existing API methods.
- Adding new properties to existing API responses.
- Changing the order of properties in existing API responses.
API Resources¶
Syntax of the URL:
https://<Tenant Id>
.bbp.local/bbp/rest/api/<API Version>
/<Tenant Id>
:<API Id>
:<API Key>
/<System Integration Identifier>
/<Resource>
Example URL: https://jmb.bbp.local/bbp/rest/api/1.0/jmb:u-19df358:357f215/ENOVIA-001/getUpdates
Resource: getUpdates¶
This resource request is sent from a client to the Business Bot platform to retrieve the latest system events (from the queue). The system events are stored on a queue which is associated to a dedicated system integration and bot.
HTTP Methode | Content Type | Resource | Description |
---|---|---|---|
POST |
application/json |
/getUpdates |
Retrieving messages events |
Request Content:
1 | {"limit":100,"offset":1,"timeout":20} |
Response Content (Example with empty result set):
1 | {"status":true, "code":200, "result":[]} |
Response Content (Example with result set):
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 | { "status": true, "code": 200, "result": [{ "updateId": 326, "message": { "reply": false, "messageId": 0, "from": { "id": 0, "firstName": "firstName", "lastName": "lastName", "userName": "john" }, "to": { "id": 0, "firstName": "firstName", "lastName": "lastName", "userName": "NO_USER" }, "date": 0, "meta": { "id": 0, "systemType": "WebUI", "systemRelease": "1.0", "eventType": "SearchRequest", "eventName": "Object", "objectId": null, "refObjectId": null }, "text": "", "audio": null, "document": null, "photo": null, "video": null, "location": null, "replyToMessage": null, "voice": null, "data": { "filter": { "objectType": "Issue", "objectName": "*", "objectRevision": "*", "objectId": null, "limit": 5, "searchString": null, "orderBy": "DESC", "tsBegin": null, "tsEnd": null, "owner": null, "view": "issuelist" }, "result": "" } } }] } |
Resource: sendUpdate¶
This resource request is sent by a client to the Business Bot platform to send a message to a mobile user.
HTTP Methode | Content Type | Resource | Description |
---|---|---|---|
POST |
application/json |
/sendUpdate |
Sending a message |
Request Content:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 | { "message": { "to": { "lastName": "lastName", "userName": "erika", "firstName": "firstName" }, "data": { "result": "[{\"type\":\"Issue\",\"name\":\"ISS-0000001\",\"revision\":\"-\",\"owner\":\"john\",\"current\":\"Create\",\"description\":\"Missing chapter\",\"objectId\":\"60592.18415.31712.43999\"},{\"type\":\"Issue\",\"name\":\"ISS-0000002\",\"revision\":\"-\",\"owner\":\"john\",\"current\":\"Create\",\"description\":\"Missing chapter\",\"objectId\":\"60592.18415.11568.63047\"}]", "filter": { "limit": 5, "orderBy": "DESC", "objectType": "Issue" } }, "from": { "lastName": "lastName", "userName": "john", "firstName": "firstName" }, "meta": { "systemType": "ENOVIA", "eventName": "Object", "eventType": "SearchResult", "systemRelease": "R2015x" } }, "updateId": "1234" } |
Response Content (Example data):
1 | {"code":200,"description":"Ok","status":"true"} |
API Error Handling¶
HTTP Status 500: No Content To Map To Object Due To End Of Input¶
If you receive the following error, an empty POST request was sent to the Business Bot platform.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 | HTTP Status 500 - org.glassfish.jersey.server.ContainerException: java.io.EOFException: No content to map to Object due to end of input type Exception report message org.glassfish.jersey.server.ContainerException: java.io.EOFException: No content to map to Object due to end of input description The server encountered an internal error that prevented it from fulfilling this request. exception javax.servlet.ServletException: org.glassfish.jersey.server.ContainerException: java.io.EOFException: No content to map to Object due to end of input org.glassfish.jersey.servlet.WebComponent.serviceImpl(WebComponent.java:487) org.glassfish.jersey.servlet.WebComponent.service(WebComponent.java:425) org.glassfish.jersey.servlet.ServletContainer.service(ServletContainer.java:383) org.glassfish.jersey.servlet.ServletContainer.service(ServletContainer.java:336) org.glassfish.jersey.servlet.ServletContainer.service(ServletContainer.java:223) org.apache.tomcat.websocket.server.WsFilter.doFilter(WsFilter.java:52) root cause org.glassfish.jersey.server.ContainerException: java.io.EOFException: No content to map to Object due to end of input org.glassfish.jersey.servlet.internal.ResponseWriter.rethrow(ResponseWriter.java:278) org.glassfish.jersey.servlet.internal.ResponseWriter.failure(ResponseWriter.java:260) org.glassfish.jersey.server.ServerRuntime$Responder.process(ServerRuntime.java:509) org.glassfish.jersey.server.ServerRuntime$2.run(ServerRuntime.java:334) org.glassfish.jersey.internal.Errors$1.call(Errors.java:271) org.glassfish.jersey.internal.Errors$1.call(Errors.java:267) org.glassfish.jersey.internal.Errors.process(Errors.java:315) org.glassfish.jersey.internal.Errors.process(Errors.java:297) org.glassfish.jersey.internal.Errors.process(Errors.java:267) org.glassfish.jersey.process.internal.RequestScope.runInScope(RequestScope.java:317) org.glassfish.jersey.server.ServerRuntime.process(ServerRuntime.java:305) org.glassfish.jersey.server.ApplicationHandler.handle(ApplicationHandler.java:1154) org.glassfish.jersey.servlet.WebComponent.serviceImpl(WebComponent.java:471) org.glassfish.jersey.servlet.WebComponent.service(WebComponent.java:425) org.glassfish.jersey.servlet.ServletContainer.service(ServletContainer.java:383) org.glassfish.jersey.servlet.ServletContainer.service(ServletContainer.java:336) org.glassfish.jersey.servlet.ServletContainer.service(ServletContainer.java:223) org.apache.tomcat.websocket.server.WsFilter.doFilter(WsFilter.java:52) root cause java.io.EOFException: No content to map to Object due to end of input org.codehaus.jackson.map.ObjectMapper._initForReading(ObjectMapper.java:2766) org.codehaus.jackson.map.ObjectMapper._readValue(ObjectMapper.java:2682) org.codehaus.jackson.map.ObjectMapper.readValue(ObjectMapper.java:1308) org.codehaus.jackson.jaxrs.JacksonJsonProvider.readFrom(JacksonJsonProvider.java:419) org.glassfish.jersey.message.internal.ReaderInterceptorExecutor$TerminalReaderInterceptor.invokeReadFrom(ReaderInterceptorExecutor.java:256) org.glassfish.jersey.message.internal.ReaderInterceptorExecutor$TerminalReaderInterceptor.aroundReadFrom(ReaderInterceptorExecutor.java:235) org.glassfish.jersey.message.internal.ReaderInterceptorExecutor.proceed(ReaderInterceptorExecutor.java:155) org.glassfish.jersey.server.internal.MappableExceptionWrapperInterceptor.aroundReadFrom(MappableExceptionWrapperInterceptor.java:74) org.glassfish.jersey.message.internal.ReaderInterceptorExecutor.proceed(ReaderInterceptorExecutor.java:155) org.glassfish.jersey.message.internal.MessageBodyFactory.readFrom(MessageBodyFactory.java:1085) org.glassfish.jersey.message.internal.InboundMessageContext.readEntity(InboundMessageContext.java:874) org.glassfish.jersey.server.ContainerRequest.readEntity(ContainerRequest.java:271) org.glassfish.jersey.server.internal.inject.EntityParamValueFactoryProvider$EntityValueFactory.provide(EntityParamValueFactoryProvider.java:96) org.glassfish.jersey.server.spi.internal.ParamValueFactoryWithSource.provide(ParamValueFactoryWithSource.java:71) org.glassfish.jersey.server.spi.internal.ParameterValueHelper.getParameterValues(ParameterValueHelper.java:94) org.glassfish.jersey.server.model.internal.JavaResourceMethodDispatcherProvider$AbstractMethodParamInvoker.getParamValues(JavaResourceMethodDispatcherProvider.java:127) org.glassfish.jersey.server.model.internal.JavaResourceMethodDispatcherProvider$ResponseOutInvoker.doDispatch(JavaResourceMethodDispatcherProvider.java:160) org.glassfish.jersey.server.model.internal.AbstractJavaResourceMethodDispatcher.dispatch(AbstractJavaResourceMethodDispatcher.java:99) org.glassfish.jersey.server.model.ResourceMethodInvoker.invoke(ResourceMethodInvoker.java:389) org.glassfish.jersey.server.model.ResourceMethodInvoker.apply(ResourceMethodInvoker.java:347) org.glassfish.jersey.server.model.ResourceMethodInvoker.apply(ResourceMethodInvoker.java:102) org.glassfish.jersey.server.ServerRuntime$2.run(ServerRuntime.java:326) org.glassfish.jersey.internal.Errors$1.call(Errors.java:271) org.glassfish.jersey.internal.Errors$1.call(Errors.java:267) org.glassfish.jersey.internal.Errors.process(Errors.java:315) org.glassfish.jersey.internal.Errors.process(Errors.java:297) org.glassfish.jersey.internal.Errors.process(Errors.java:267) org.glassfish.jersey.process.internal.RequestScope.runInScope(RequestScope.java:317) org.glassfish.jersey.server.ServerRuntime.process(ServerRuntime.java:305) org.glassfish.jersey.server.ApplicationHandler.handle(ApplicationHandler.java:1154) org.glassfish.jersey.servlet.WebComponent.serviceImpl(WebComponent.java:471) org.glassfish.jersey.servlet.WebComponent.service(WebComponent.java:425) org.glassfish.jersey.servlet.ServletContainer.service(ServletContainer.java:383) org.glassfish.jersey.servlet.ServletContainer.service(ServletContainer.java:336) org.glassfish.jersey.servlet.ServletContainer.service(ServletContainer.java:223) org.apache.tomcat.websocket.server.WsFilter.doFilter(WsFilter.java:52) note The full stack trace of the root cause is available in the Apache Tomcat/8.0.38 logs. Apache Tomcat/8.0.38 |
HTTP Status 415: Unsupported Media Type¶
If you receive the following error, the content type expected by the Business Bot Platform does not match application/json
.
1 2 3 4 5 6 7 8 | HTTP Status 415 - Unsupported Media Type type Status report message Unsupported Media Type description The server refused this request because the request entity is in a format not supported by the requested resource for the requested method. Apache Tomcat/8.0.38 |
HTTP Status 500: org.json.JSONException: Expected a ',' or '}' at 724 [character 1 line 37]¶
If you receive the following error, the request content is incorrect, in this example the JSON content is invalid.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 | HTTP Status 500 - org.json.JSONException: Expected a ',' or '}' at 724 [character 1 line 37] type Exception report message org.json.JSONException: Expected a ',' or '}' at 724 [character 1 line 37] description The server encountered an internal error that prevented it from fulfilling this request. exception javax.servlet.ServletException: org.json.JSONException: Expected a ',' or '}' at 724 [character 1 line 37] org.glassfish.jersey.servlet.WebComponent.serviceImpl(WebComponent.java:487) org.glassfish.jersey.servlet.WebComponent.service(WebComponent.java:425) org.glassfish.jersey.servlet.ServletContainer.service(ServletContainer.java:383) org.glassfish.jersey.servlet.ServletContainer.service(ServletContainer.java:336) org.glassfish.jersey.servlet.ServletContainer.service(ServletContainer.java:223) org.apache.tomcat.websocket.server.WsFilter.doFilter(WsFilter.java:52) root cause org.json.JSONException: Expected a ',' or '}' at 724 [character 1 line 37] org.json.JSONTokener.syntaxError(JSONTokener.java:433) org.json.JSONObject.<init>(JSONObject.java:232) org.json.JSONObject.<init>(JSONObject.java:324) de.citunius.bbp.adk.services.WebService.isValidRawMessage(WebService.java:348) de.citunius.bbp.adk.services.WebService.sendMessageRequest(WebService.java:391) sun.reflect.NativeMethodAccessorImpl.invoke0(Native Method) sun.reflect.NativeMethodAccessorImpl.invoke(Unknown Source) sun.reflect.DelegatingMethodAccessorImpl.invoke(Unknown Source) java.lang.reflect.Method.invoke(Unknown Source) org.glassfish.jersey.server.model.internal.ResourceMethodInvocationHandlerFactory$1.invoke(ResourceMethodInvocationHandlerFactory.java:81) org.glassfish.jersey.server.model.internal.AbstractJavaResourceMethodDispatcher$1.run(AbstractJavaResourceMethodDispatcher.java:144) org.glassfish.jersey.server.model.internal.AbstractJavaResourceMethodDispatcher.invoke(AbstractJavaResourceMethodDispatcher.java:161) org.glassfish.jersey.server.model.internal.JavaResourceMethodDispatcherProvider$ResponseOutInvoker.doDispatch(JavaResourceMethodDispatcherProvider.java:160) org.glassfish.jersey.server.model.internal.AbstractJavaResourceMethodDispatcher.dispatch(AbstractJavaResourceMethodDispatcher.java:99) org.glassfish.jersey.server.model.ResourceMethodInvoker.invoke(ResourceMethodInvoker.java:389) org.glassfish.jersey.server.model.ResourceMethodInvoker.apply(ResourceMethodInvoker.java:347) org.glassfish.jersey.server.model.ResourceMethodInvoker.apply(ResourceMethodInvoker.java:102) org.glassfish.jersey.server.ServerRuntime$2.run(ServerRuntime.java:326) org.glassfish.jersey.internal.Errors$1.call(Errors.java:271) org.glassfish.jersey.internal.Errors$1.call(Errors.java:267) org.glassfish.jersey.internal.Errors.process(Errors.java:315) org.glassfish.jersey.internal.Errors.process(Errors.java:297) org.glassfish.jersey.internal.Errors.process(Errors.java:267) org.glassfish.jersey.process.internal.RequestScope.runInScope(RequestScope.java:317) org.glassfish.jersey.server.ServerRuntime.process(ServerRuntime.java:305) org.glassfish.jersey.server.ApplicationHandler.handle(ApplicationHandler.java:1154) org.glassfish.jersey.servlet.WebComponent.serviceImpl(WebComponent.java:471) org.glassfish.jersey.servlet.WebComponent.service(WebComponent.java:425) org.glassfish.jersey.servlet.ServletContainer.service(ServletContainer.java:383) org.glassfish.jersey.servlet.ServletContainer.service(ServletContainer.java:336) org.glassfish.jersey.servlet.ServletContainer.service(ServletContainer.java:223) org.apache.tomcat.websocket.server.WsFilter.doFilter(WsFilter.java:52) note The full stack trace of the root cause is available in the Apache Tomcat/8.0.38 logs. Apache Tomcat/8.0.38 |