Resources for Working with the REST Service Broker
KB001786
PRODUCTK2 Cloud
K2 Five
K2 blackpearl 4.7
K2 Five (5.1) November 2018 Cumulative Update Fix Pack 12
The REST broker, shipped with K2 4.7, K2 Five, and K2 Cloud allows you to integrate K2 with REST-based services. There are several resources available to you for getting up-to-speed on what you need to use these services from K2.
Resources
- REST Service Type (K2 Five, K2 Cloud). The documentation of the REST broker, including helpful video links describing how to configure the service.
- REST Swagger File Reference Format (K2 Five, K2 Cloud) The schema of the Swagger file with examples, limitations, how to handle files in the response, and when to use a root object to contain the payload results from the service.
- Swagger Templates on K2 Community: Find community-supported Swagger files for integrating with a number of different services.
Review this file reference format topic carefully while planning your REST service integration to learn about potential limitations of the Swagger format that can impact the feasibility of this approach. An alternative (if the REST broker cannot be used to integrate with the service) is to write a custom broker to handle things like dynamic field names, field names with numbers, and OAuth 1.0-based services.
How do I obtain a Swagger file?
There are several ways to get a Swagger file for use with the REST broker.
If your company DOES NOT provide or own the REST API endpoints:
- Recommended: Work with the REST API endpoint provider or vendor directly. Most services providing REST APIs also provide a Swagger file, and you can download it directly from them or request a Swagger file. Alternatively, you can check APIGurus who provide examples: https://apis.guru/browse-apis/
- Alternate #1: Use RESTUnited.com to generate a Swagger file based on example responses. See http://help.k2.com/kb001758 for more information.
- Alternate #2: Generate a Swagger file manually.
If your company DOES provide or own the REST API endpoints:
- Recommended: Use the Swashbuckle library to add Swagger to your project. See http://help.k2.com/kb001869 for more information.
- Alternate #1: Use RESTUnited.com to generate a Swagger file based on example responses. See http://help.k2.com/kb001758 for more information.
- Alternate #2: Generate a Swagger file manually.
KB Resources
- Integrating a REST-based Service with K2: http://help.k2.com/kb001757. From basic architecture to writing your own SmartWizards, this is the end-to-end article on the power of the REST broker in the K2 platform.
- How To: Generate a Swagger Descriptor for REST-based Services using Swashbuckle: http://help.k2.com/kb001869. Learn how to add the Swashbuckle NuGet project to your API to generate Swagger. This is useful if you control the source code.
- Generating a Swagger Descriptor for REST-based Services using RESTUnited.com: http://help.k2.com/kb001758. Use this to discover how to generate a Swagger file for your custom or well-known REST service. This is useful if you do NOT control the source code.
- Using the REST Service Broker with Azure API Apps: http://help.k2.com/kb001781. Use this to learn how to create an Azure API app and call it using the REST broker.
Online Swagger Files
Linked to from other documentation and videos, you can use these Swagger descriptor files for testing purposes:
- PetStore: https://raw.githubusercontent.com/K2Documentation/K2Documentation.Samples.JSON/master/PetStore/PetStore.json
- OpenWeatherMap: https://raw.githubusercontent.com/K2Documentation/K2Documentation.Samples.JSON/master/OpenWeatherMap/OpenWeatherMap.json
- Swagger Templates on K2 Community: Find community-supported Swagger files for integrating with a number of different services.
Related Resources
- How to configure OAuth in K2: http://help.k2.com/kb001702. This is a standalone topic that explains how to configure an OAuth resource in K2. That resource can be used for any broker that supports OAuth, including REST.
- OAuth authentication with Azure OData Web Services: http://help.k2.com/kb001751. Use this to learn how to configure an OAuth resource for use when calling Azure OData web services using the OData broker.
- Creating Swagger descriptor file for SharePoint Search using RESTUnited, Fiddler and Notepad++: https://www.dragan-panjkov.com/creating-swagger-descriptor-file-for-sharepoint-search-using-restunited-fiddler-and-notepad. Use this blog post to learn how Dragan Panjkov worked through creating a descriptor file for SharePoint Search.
