Learn how to mobilize your APIs by configuring and using Kinvey’s RAPID REST Data Connector with API proxies configured in Apigee Edge.
We are seeing an increasing number of organizations adopting Progress Kinvey to mobilize their enterprise APIs. This includes API Management Platforms like Apigee, MuleSoft, CA Technologies, Tibco Mashery, and others that are not specifically engineered for mobility. Kinvey integrates these APIs via its no code RAPID or low code FLEX connectors.
In this post we will take a closer look at how to configure and use Kinvey’s RAPID REST Data Connector with API proxies configured in Apigee Edge. If you are new to Apigee or Kinvey be sure to check-out the following resources:
Okay so let’s get started.
I am going to assume you have already configured your API proxies in Apigee to serve your REST API to internal/external developers. If not, I recommend signing up for a free trial account and use the link above to learn more on how to do this.
For my setup, I created a spec in Apigee for an endpoint called “posts” representing blog posts. I then created an Api proxy and attached it to an actual backend REST API endpoint “/posts” served using JSONPlaceholder. Apigee can deploy the proxy to a test/prod environment each of which has a url which can be configured in the Kinvey RAPID Connector. The URL I got for my posts spec proxy was http://sameer-eval-prod.apigee.net/posts
Now let’s look at how I intend to wire everything up with Kinvey. Pretty straightforward.
RAPID data configuration on Kinvey begins by creating a data service. Head over to your Kinvey Console and click the Service Catalog in the top nav. The Service Catalog is where you find a list of all the services you have access to. These could be services in an organization or a particular app. You can sort the list by type (auth, data or flex) or use the search box. Have fun with the filters later! For now we just need to add a new service so click the green button!
You should now see a popup asking you to select the type of service. Choose RapidData > REST.
Before we go any further let’s take a moment to appreciate the ready to use no code data connectors Kinvey offers. This is just one of the many ways Kinvey accelerates app development. Don’t be disheartened if you don’t see your system of record in this list. You can still easily connect to it using one of our easy to use reference flex connectors which are low code.
Okay, back to business! So if you successfully clicked the mouse button you should now see a screen similar to what I’m about to present. Although this form is pretty self-explanatory let’s still go over it after the screenshot.
Name: Give your service a name. It could be ANYTHING.
Description: Write a note about what this service does, what it connects to etc.
App: This one is important! Select the Kinvey app that you want to associate with this service.
Host: This is where you will put your Proxy URL from Apigee. Notice how I removed the “/posts” at the end. This endpoint will be configured in the Service Object we create next.
Static Headers: Provision to pass any headers that you would like to include in every request. This is optional.
Query Params: Query params to be included in every request. This is optional
Authentication Type: In most cases an API Management Platform secures API access but for the sake of simplicity I did not choose to add an auth layer to my Apigee Proxy. However, if your setup requires authentication you can configure it here easily.
Click Save to finish. It’s time now to create Service Objects in Kinvey for our endpoints. A Service Object allows Kinvey to interact with records or data objects on an external system. I will create one called “posts.” A Service Object is similar to your API spec in Apigee. This time, let’s review the fields in the form first before I share a screenshot of my config.
Name: This is the name of your Service Object. You could call this anything but I recommend keeping the same name as your endpoint. So if that is “/posts”, name the Service Object “posts.” Please note that this name will be used by developers to reference the endpoint within Kinvey.
Endpoint: This is relative to the “host” you put in the previous form. Enter the URI part that identifies the specific resource. For me this is “/posts”
Context Root: Optionally allows you to extract nested data from server responses. This means you can return just a subset of the actual response. For example: Let’s say your API response has an object called “body” amongst other things. If you just want to return this object set the Context Root property to “body.”
Primary Key Type: Select the type of the property that uniquely identifies the resource: number (int) or string.
Primary Key Name: Enter the name of the property that uniquely identifies the resource.
Query Mapping: Allows you to customize the way queries are passed from Kinvey to the remote REST API.
HTTP Method: This is the default verb to use when making requests to the external REST API (Apigee Proxy). My Proxy accepts GET which is also the default value of this field so I’ll leave it blank.
Static Headers: Allows you to add any custom, static string values as a header to be included in every request to the API. Tokens are also supported.
Query Parameters: Allows you to add any custom, static string values as a query string parameter to be included in every request to the API. Tokens are also supported.
Supported Operations: Use the toggle to enable/disable any operation. This gives you another layer of security on top of the spec defined in Apigee. Any request sent to Kinvey for a operation not enabled here receives the “405 METHOD NOT ALLOWED” error.
Field Mapping: Use this to control what fields are exposed. By default service fields are mapped automatically to similarly named Kinvey Fields.
If you want more control like me, click “Discover Fields” to automatically retrieve the fields your API exposes. Once you do this you should see the number of fields Kinvey retrieved and a button next to it “Add All.” Click “Add All” to either review or change the default mappings. To define custom mappings Click “Add Non Default Field Mapping.” Nested fields are supported. Use dot notation to map these eg: “body.title.”
Important: We recommend you map your primary key to the Kinvey “_id” field. I’ve highlighted how I’ve done this in the screens below.
Tip: “Discover Fields” can also be used as a test to see if your host and endpoint are accessible by Kinvey.
And as promised, here is my service object configuration for the “/posts” endpoint. It’s a long form so I’ll do this in two screenshots.
Congratulations! We have completed the setup and it’s time now to test our service. Let’s do this by creating a new collection (or use an existing one) and change its data source to point to the Rapid REST Service Data Object “posts” we just created. By default when you create a Kinvey collection, it’s data source is set to the Kinvey Data Store which uses MongoDB behind the scenes and is managed entirely by Kinvey, just for you! But you can change that to use a service instead which is exactly what we are going to do.
Click collections in the left menu on your Kinvey Console and from the list of collections that show up, click the one you want to use or add a new one. You should now see the Collection settings and under Data Source “Use Kinvey Data Store” would be selected. Click on “Use Data Service” instead, then select your service from the list and then choose the service object you created.
That’s it! Now every request to the collection will be fulfilled by the data service. Let’s make one to see if it works. Click “API Console” from the menu, choose the collection from the list and select GET as the method. API Console is an HTTP Client built into Kinvey, similar to POSTMAN and it’s great for testing quick requests. Here is what the API Console looks like.
FUN FACT: If you have a mobile app which queries that collection already, just refresh the view and you should see results come in from Apigee now. Amazing right?
Well that’s Kinvey Rapid for you! If you're interested in trying it for yourself, head over to the console and sign up for a free account.
Sign Up for Free
Sameer Maira is a Solution Architect working on Progress Kinvey. He works closely with customers and partners to help them with their mobile app architecture and provide technical support. Sameer enjoys research and development and has several years of experience developing and supporting enterprise apps and solutions. Besides technology, Sameer is passionate about song-writing and food!
Copyright © 2018 Progress Software Corporation and/or its subsidiaries or affiliates.
All Rights Reserved.
Progress, Telerik, and certain product names used herein are trademarks or registered trademarks of Progress Software Corporation and/or one of its subsidiaries or affiliates in the U.S. and/or other countries. See Trademarks for appropriate markings.