{"id":6669,"date":"2019-04-15T07:26:38","date_gmt":"2019-04-15T14:26:38","guid":{"rendered":"https:\/\/www.couchbase.com\/blog\/?p=6669"},"modified":"2019-05-17T12:35:20","modified_gmt":"2019-05-17T19:35:20","slug":"generating-couchbase-api-dreamfactory","status":"publish","type":"post","link":"https:\/\/www.couchbase.com\/blog\/generating-couchbase-api-dreamfactory\/","title":{"rendered":"Generating Couchbase APIs with DreamFactory"},"content":{"rendered":"\r\n

This is a guest post written by W. Jason Gilmore (https:\/\/www.wjgilmore.com<\/a>) the CTO of DreamFactory, Inc., an open source API automation and management platform. Prior to joining DreamFactory he spent much of his career as a consultant and developer, helping teams around the globe build amazing software solutions. Jason is a prolific writer on the subject of web technologies with almost a dozen books and more than 300 articles to his credit. He serves as a special technical advisor for several startups based in Ohio and New York.<\/em><\/p>\r\n\r\n\r\n\r\n

\"Jason<\/figure>\r\n\r\n\r\n\r\n

Modern organizations are under tremendous pressure to efficiently process and incorporate data into every initiative. In fact, the emphasis placed upon extracting, compiling, analyzing, and disseminating information is such that an entirely new field of study known as data science<\/strong> has emerged to make sense of it all (for those of you thinking this sounds suspiciously academic, take note that Harvard Business Review called data science The Sexiest Job of the 21st Century<\/a>.<\/p>\r\n\r\n\r\n\r\n

The Need for APIs<\/h2>\r\n\r\n\r\n\r\n

In addition to formalizing the data management process, IT teams have increasingly embraced heterogeneous database environments and API-driven development in an effort to ensure data can be ingested, processed, and distributed with minimal friction. Gone are the days when an entire organization standardizes upon a particular database vendor; instead, it\u2019s now commonplace for enterprises to embrace a mixture of both commercial and open source SQL and NoSQL solutions.<\/p>\r\n\r\n\r\n\r\n

Of course, there must be some sane way to manage data as it flows through these databases, and that\u2019s where APIs come in. Because databases must often be queried from a variety of applications (iOS, web, etc.), developers have in recent years eschewed application-specific libraries in preference for APIs. By creating and plugging into a uniform API, developers can focus on the application itself rather than database-related plumbing.<\/p>\r\n\r\n\r\n\r\n

Enter DreamFactory<\/h2>\r\n\r\n\r\n\r\n

Or at least that\u2019s the idea. The reality is, building and maintaining a database API is an extraordinarily time-consuming and costly endeavor. While an experienced team can build a CRUD API interface in perhaps a few weeks, they often don\u2019t take into consideration the many additional requisite features necessary for API management. Capabilities such as authentication and authorization, request volume limiting, caching, and logging are often not considered when planning an API, and figuring out how to implement these capabilities in a piecemeal fashion can be extraordinarily difficult and costly.<\/p>\r\n\r\n\r\n\r\n

Many organizations avoid these headaches by adopting an API management platform<\/strong>. One particularly popular such solution is DreamFactory<\/a>. Not only is it open source (commercial versions offering advanced capabilities are also available), but it also includes native support for Couchbase! In this post you\u2019ll learn how to generate a Couchbase REST API using DreamFactory in just minutes, and then lock down API access using DreamFactory\u2019s role management feature.<\/p>\r\n\r\n\r\n\r\n

Introducing DreamFactory<\/h2>\r\n\r\n\r\n\r\n

DreamFactory<\/a> is an API automation and management framework used by tens of thousands of organizations around the globe. Although its popularity largely stems from the ability to generate full featured, documented, and secure APIs for a variety of SQL and NoSQL databases with no coding required, DreamFactory actually supports thousands of data sources and third-party services, including e-mail delivery providers, mobile notification services including AWS SNS, Apple and GCM Push, and for converting SOAP services to REST.<\/p>\r\n\r\n\r\n\r\n

DreamFactory supports a total of 18 databases, including MySQL, Oracle, Microsoft SQL Server, and\u2026\u200b Couchbase! Generating an API is very straightforward, requiring only the provision of a desired API name and Couchbase server credentials. To create an API, you\u2019ll begin by logging into the DreamFactory web administration interface. You\u2019ll be able to access DreamFactory\u2019s key features via the navigational bar:<\/p>\r\n\r\n\r\n\r\n

\"DreamFactory<\/figure>\r\n\r\n\r\n\r\n

Create the service by clicking on Services<\/code> then Create<\/code>, then choose Couchbase<\/code> from the Database<\/code> category:<\/p>\r\n\r\n\r\n\r\n

\"Select<\/figure>\r\n\r\n\r\n\r\n

Next you\u2019ll choose an API name, and set a label and description. The name is particularly important, because as you\u2019ll see this will serve as a namespace of sorts for your generated API. The label and description are just for reference purposes within the administration interface:<\/p>\r\n\r\n\r\n\r\n

\"Couchbase<\/figure>\r\n\r\n\r\n\r\n

After completing these fields, click on the Config<\/code> tab and supply your Couchbase credentials:<\/p>\r\n\r\n\r\n\r\n

\"Completed<\/figure>\r\n\r\n\r\n\r\n

In addition to the Host<\/code>, Port<\/code>, Username<\/code> and Password<\/code> fields, you can optionally cap the number of records returned by a GET<\/code> request, and enable data caching for a set period of time. For the purposes of this tutorial I\u2019ll leave those options untouched and just generate the API by pressing the Save<\/code> button.<\/p>\r\n\r\n\r\n\r\n

Interacting with the API<\/h2>\r\n\r\n\r\n\r\n

Once the API has been generated, you can navigate to the API Docs<\/code> interface to experiment with it. DreamFactory generates Swagger documentation for each API, and administrators can provide users with restricted access to this documentation. Select the new API, and you\u2019ll be presented with a list of all available endpoints:<\/p>\r\n\r\n\r\n\r\n

\"API<\/figure>\r\n\r\n\r\n\r\n

Choose the GET \/_schema<\/code> endpoint and press the Try it out<\/code> button. Because Swagger documentation is interactive, you can learn how the API works without having to jump straight into code, which can greatly decrease frustration. Pressing Try it out<\/code> will enable the various parameter fields associated with this endpoint:<\/p>\r\n\r\n\r\n\r\n

\"Detailed<\/figure>\r\n\r\n\r\n\r\n

NOTE: Because of the breadth of supported databases, and the importance placed on providing a uniform database API interface regardless of the underlying database type, DreamFactory uses generic terms for referring to database-related structures. Logically, these terms don\u2019t always map exactly to database-specific terminology. For instance Couchbase uses the term bucket<\/strong> to represent a database, whereas DreamFactory uses the generic term schema<\/strong> for this representation.<\/em><\/p>\r\n\r\n\r\n\r\n

Press the Execute<\/code> button and the API endpoint will be queried, returning all available buckets. Couchbase users will be familiar with the travel-sample<\/code> bucket returned in the following response:<\/p>\r\n\r\n\r\n\r\n

\"Example<\/figure>\r\n\r\n\r\n\r\n

Accessing data from the API<\/h2>\r\n\r\n\r\n\r\n

Next, scroll down to the GET \/_table\/{table_name}<\/code> endpoint to retrieve records (documents) from the travel-sample<\/code> bucket. The process for doing so is similar to that used for retrieving the buckets; you\u2019ll select the endpoint, press Try it out<\/code>, and then enter any desired API endpoint parameters. As you can see from the below screenshot, this endpoint supports quite a few parameters:<\/p>\r\n\r\n\r\n\r\n

\"API<\/figure>\r\n\r\n\r\n\r\n

When it comes to selecting records, DreamFactory supports everything you\u2019d typically do when querying a database. You can select specific fields, join tables, filter records, apply limits and offsets, and so forth. For this example let\u2019s just keep it simple and scroll down to the bottom of the parameter list and enter travel-sample<\/code> into the table_name<\/code> parameter. Press Execute<\/code> and you\u2019ll see the following results:<\/p>\r\n\r\n\r\n\r\n

\"Couchbase<\/figure>\r\n\r\n\r\n\r\n

Generating a Restricted API Key<\/h2>\r\n\r\n\r\n\r\n

The API Docs interface is great for learning more about how an API works, however you\u2019ll inevitably want to begin querying the API from a web or mobile application. To do so, you\u2019ll want to first generate an API key<\/strong>. This is because DreamFactory doesn\u2019t support the concept of a public API; all APIs are protected by at minimum an API key. Further, each API key is mapped to a role<\/strong>. DreamFactory roles determine what it is a client in possession of an API key can do in conjunction with the API. For instance, you might create a role that is read-only, or which might only allow access to a specific database table, or which might only be able to insert records into one table but read records from another table.<\/p>\r\n\r\n\r\n\r\n

To create a role, navigate to the Roles<\/code> tab, and press Create<\/code>. You\u2019ll assign a role name and description, and then click the Access<\/code> tab. It\u2019s here where the magic happens. In the following screenshot you\u2019ll see I\u2019ve selected the couchbase<\/code> API (service), and set Component<\/code> to _table\/travel-sample\/*<\/code>, meaning the role can only access this particular data set. Further, I\u2019ve set Access<\/code> to GET<\/code>, meaning this will be a read-only role:<\/p>\r\n\r\n\r\n\r\n

\"Create<\/figure>\r\n\r\n\r\n\r\n

There are a few other interesting features here, however for the sake of brevity I suggest just pressing Save<\/code> to generate the role.<\/p>\r\n\r\n\r\n\r\n

Next, click on the Apps<\/code> tab to generate an API key. Press the Create<\/code> button and you\u2019ll be presented with the following interface:<\/p>\r\n\r\n\r\n\r\n

\"Create<\/figure>\r\n\r\n\r\n\r\n

Here you\u2019ll supply an application name and description. You\u2019ll also choose a role for this API key, and in this example I\u2019ve selected the newly generated couchbase<\/code> role. Finally, for the App Location<\/code> I\u2019ve selected No storage required<\/code> because I\u2019ll be connecting to the API from a remote location such as a web application. Press Save<\/code> and you\u2019ll be returned to the application key listing:<\/p>\r\n\r\n\r\n\r\n

\"Create<\/figure>\r\n\r\n\r\n\r\n

Congratulations, you\u2019ve just created a restricted read-only API key! Now let\u2019s use that key to talk to the Couchbase bucket.<\/p>\r\n\r\n\r\n\r\n

Connecting to your API<\/h2>\r\n\r\n\r\n\r\n

With your API key in hand, it\u2019s time to interact with the API from outside of the DreamFactory interface. For the purposes of this example I\u2019ll use the Insomnia REST client<\/a> however you\u2019re free to use Postman<\/a>, another API client, or certainly can build out a simple web or iPhone interface. In the following screenshot I\u2019ve queried the \/api\/v2\/couchbase\/_table\/travel-sample<\/code> endpoint, and on the right-side of the interface you can see the results:<\/p>\r\n\r\n\r\n\r\n

\"Using<\/figure>\r\n\r\n\r\n\r\n

Of particular importance here is the X-DreamFactory-Api-Key<\/code> header! It\u2019s here where the API key is supplied. Neglecting to supply the key will result in a 400<\/code> status code with an error message pertaining to a missing key. Additionally, if this key attempts to access a restricted table or perform an action (insert, update, etc) that hasn\u2019t been expressly allowed within the role definition, a 401<\/code> unauthorized status code will be returned.<\/p>\r\n\r\n\r\n\r\n

Resources<\/h2>\r\n\r\n\r\n\r\n

Hopefully this introduction to DreamFactory got your mind racing regarding how quickly you can begin building Couchbase-backed applications. If you\u2019re interested in learning more the following resources should be useful:<\/p>\r\n\r\n\r\n\r\n