Review: REST United Automatically Generates SDKs for REST APIs

REST United is a fairly new online application for automatically generating SDKs for REST APIs. REST United features an easy-to-use interface that allows users to build automatically generated SDKs (REST API libraries) with customizable documentation and code samples.

A few other examples of platforms designed specifically for automatic SDK generation include APIMATIC, Restlet Studio, and Swagger Codegen. Magnet rest2mobile automatically generates native code mobile SDKs from RESTful APIs.

There are quite a few API management platforms and API builders that feature automatically generated API documentation and code samples, including 3scale, Akana (formerly SOA Software), Apiary, Apigee, Apigility, CA API Management, Microsoft Azure App Service API Apps, and MuleSoft Anypoint Platform. With the exception of Microsoft Azure App Service API Apps, these platforms feature automatically generated API documentation and code samples, but do not feature automatic SDK generation.

Automatic generation of SDKs is a difficult prospect; there are many things that need to be considered when attempting to automatically generate code. Missing information such as model definitions, error codes, and authentication information can cause automatically generated code to be of very poor quality, and in some cases, the code will not even work. API design is also a major factor when attempting to automatically generate code. There is no single, widely adopted, industry-agreed-upon design standard for APIs. Not to mention that some APIs are designed well while others are poorly designed, returning badly formatted JSON and/or producing unexpected results.

This article is an in-depth review of REST United, highlighting key features of the platform. This article also takes a brief look at developer experience (DX) when it comes to REST United automatically generated SDKs.

Easy to Use Interface

rest-wizard

The REST API Wizard allows users to build automatically generated SDKs in five steps.

REST United allows users to build, generate, and manage automatically generated SDKs and API documentation. REST United features an easy-to-use interface with a new REST API Wizard, Import REST API tool, tutorial mode, informational tool tips, and more.

The REST API Wizard guides users through a five-step process for entering API information and building a set of SDKs with API documentation. A few of the steps are a bit lengthy; however, there are text explanations and informational tool tips that help make the process pretty easy.

Import REST API Tool

rest-import

REST United features an Import REST API tool that allows users to build SDKs by importing API description files. At the time of this writing, REST United supports Postman, Alpaca, Swagger (v1.2, v2.0), 3scale, I/O Docs, and Blueprint.

The Import REST API tool worked as expected for all API description file types except for the Postman collection file. REST United customer service figured out the issue (an API method name in the file beginning with numbers) and fixed the Postman collection file import problem very quickly. So far, I’ve been able to import Postman collection files successfully with no further issues.

While REST United does support a nice range of API description file formats, ProgrammableWeb would like to see the platform also support RAML description files and Google APIs Discovery documents.

Tutorial Mode

tutorial-mode

REST United features a “tutorial mode” that walks new users through the steps in the SDK building process. Tutorial mode is very helpful for new users of the service as well as developers not all that familiar with APIs.

Extensive technical knowledge is not required to use REST United. However, the application is easier to use for those experienced in designing or consuming APIs.

Postman Support

postman-export

Screenshot of Postman with APIs imported from a Postman collection file that was exported from REST United.

REST United supports import and export of Postman collection files. Postman collection file export is a key feature of REST United as it allows users to easily leverage Postman for testing and debugging their APIs.

At the time of this writing, REST United is the only automatic SDK generation platform that we were able to find that features built-in Postman collection file import and export.

Swagger Support

swagger-petstore

REST United supports the Swagger API definition format and is able to import and export Swagger files (both v1.2 and v2.0). Swagger is a popular framework for APIs and many automatic SDK generation platforms and API management platforms feature built-in Swagger support.

Customizable Documentation

docs-default

Screenshot of the default documentation. Companies can insert their own logo and add information such as pricing, rate limiting, etc.

REST United allows users to automatically generate API documentation, which is hosted by REST United. The API documentation generated includes SDK installation information, code samples, links to the SDKs, release notes, and other API information.

custom-docs

Screenshot of customized documentation.

The API documentation can be customized using Bootstrap and/or highlight.js CSS themes. There are quite a few pre-built Bootstrap themes available at Bootswatch.com. The sections with code samples can be customized using highlight.js CSS themes. You can find a nice collection of highlight.js CSS themes at the cdnjs Library Repository.

Miscellaneous Features

model-wizard

REST United features a model wizard that automatically creates an API model when an example JSON response is provided. The platform also allows users to submit their own error codes and includes default error codes such as 400, 502, 503, etc. At the time of this writing, REST United supports authenticated API endpoints including HTTP Basic Auth, API Key, and OAuth 2.0.

Automatic SDK Generator

sdk-build

The key feature of REST United is the capability to automatically generate SDKs. Once all of the API endpoint information is entered, either by using the new REST API Wizard or by importing an API description file, users can generate SDKs for their preferred languages.

At the time of this writing, REST United is capable of automatically generating SDKs for programming languages including Android, C#, ActionScript, Java, Objective-C, PHP, Python v2, Ruby, and Scala. REST United also recently added beta support for JavaScript and Node.js SDKs.

The APIs that were used to test and review REST United’s automatically generated SDKs include AlchemyAPI, MusicGraph, and Open States. Only the PHP and Python SDKs were tested for this review as those are my preferred programming languages.

Using the REST API Wizard sometimes produces better results than using the Import REST API Tool. The REST API Wizard is a step-by-step process that makes sure all the necessary information is entered by the user. Importing API definition files is faster, but a poor quality API definition file will cause problems with the SDK building process.

Python SDK

python-1

The REST United Python SDK displays the API response in a neat, human-readable format.

The Python SDK is easy to install, although I did have to install a few additional Python modules not mentioned in the documentation: python-dateutil and var_dump. For any company providing SDKs, I would suggest listing all the modules required to use the SDK in the documentation. Linking to the modules’ Python Package Index (PyPI) profile would also be helpful.

The Python SDK did not work as expected intially; the API response was returned as shown in the screenshot below:

python-2

When the API response came back as memory addresses, I thought the Python SDK didn’t work. I spent quite a bit of time researching the result of the Python code, thinking that I must have done something wrong. I expected the Python SDK code to return the API response in either JSON format or at least a human-friendly, readable format.

After contacting REST United customer service, I found out that the expected result of the Python SDK was to return memory addresses when using pprint on an object. They suggested using Python var_dump to dump all the properties recursively.

For any company providing SDKs, I would suggest that if the SDK does not return JSON as the final format, then it should be noted prominently in the documentation. This will save the developer a lot of time in unnecessary troubleshooting and debugging.

REST United has since updated the Python SDK so that it no longer returns memory addresses when using pprint. The SDK now displays the API response in a neat, human-readable format.

PHP SDK

php-1

I was able to successfully install the PHP SDK quickly and it worked as expected. The PHP SDK originally used var_dump to display the API response, but REST United has since updated the SDK and documentation so that print_r is used instead.

To make the API response a little easier to read, I added <pre></pre> tags to the PHP code.

Conclusion

When it comes to building SDKs with REST United, many API providers should be able to use the application to build SDKs for their REST APIs fairly easily and quickly.

When it comes to SDKs, whether they are automatically generated or manually coded, developers are looking for SDKs that:

  • Take only minutes to install
  • Are very easy to use
  • Code is easy to understand, easy to modify
  • Work right out of the box (no errors, no troubleshooting, no debugging)
  • Return API responses in formats that are usable

Last year, ProgrammableWeb published an article explaining that developer experience (DX) is key to a successful API. This can also be said when it comes to an SDK.

REST United SDK Generator is currently in beta, so there are still some bugs that need to be worked out. However, if REST United is able to generate SDKs that are quick to install, easy to use, and work out of the box, it could become a must-have tool for API providers and a beneficial tool for API consumers.

Be sure to read the next SDK article: Microsoft Updates Windows 10 SDK Ahead of General Release

 

Comments (5)

jwagner

Thanks for posting a link to the API Evangelist article that compares automatic API code generation tools for Swagger. It's a good article.

kaneda

John has a more recent comparision of the SDK generators: http://blog.jongallant.com/2015/09/api-sdk-generators.html#comment-26718.... Here is his finding:

#######

1) AutoRest:

https://github.com/Azure/autor... is pretty active, open-source but the auto-generated SDKs lack some important features such as authentication: https://github.com/Azure/autor...

2) APIMatic:

Given that it's not open-source, a simple search in GitHub shows some low-level issues (failed to compile, etc) with the SDKs generated by APIMatic: https://github.com/search?o=de...

3) Alpaca

Last commit was Apr 15, 2015 so seems like it's no longer active.

4) RESTUnited

It uses SwaggerCodegen as the code generator and also generates documentation and hosts it for you.

5) Swagger-Codegen:

https://github.com/swagger-api... is also very active, open-source but the fact that it's too active means a feature request or issue report may take a while to get a reply from the team as they seem to be very busy.

My suggestion:

If you're a fanboy of MS technology, go for AutoRest, otherwise Swagger-Codegen.

#######

kaneda

John Davidson has a better comparsion of SDK generators worth sharing:

####

Here is a more realistic comparison of the SDK generators by looking at the issues with the auto-generated SDKs:

1) AutoRest:

https://github.com/Azure/autor... is pretty active, open-source but the auto-generated SDKs lack some important features such as authentication: https://github.com/Azure/autor...

2) APIMatic:

Given that it's not open-source, a simple search in GitHub shows some low-level issues (failed to compile, etc) with the SDKs generated by APIMatic: https://github.com/search?o=de...

3) Alpaca

Last commit was Apr 15, 2015 so seems like it's no longer active.

4) RESTUnited

It uses SwaggerCodegen as the code generator and also generates documentation and hosts it for you.

5) Swagger-Codegen:

https://github.com/swagger-api... is also very active, open-source but the fact that it's too active means a feature request or issue report may take a while to get a reply from the team as they seem to be very busy.

My suggestion:

If you're a fanboy of MS technology, go for AutoRest, otherwise Swagger-Codegen.

####

Ref: http://blog.jongallant.com/2015/09/api-sdk-generators.html#comment-26718...