Documenting REST APIs in the Source Code

By Niklas Heidloff, posted on May 28, 2014

There are several tools available that help documenting REST APIs. One of them is Swagger, an open source project under the Apache 2 license.

"The goal of Swagger™ is to define a standard, language-agnostic interface to REST APIs which allows both humans and computers to discover and understand the capabilities of the service without access to source code, documentation, or through network traffic inspection."

For REST APIs implemented in Java you can use Java annotations to document the REST APIs directly in the source code so that documentation and actual APIs are not out of synch. As part of this documentation you can not only define what parameters, types, etc. a service has but also which parameters are mandatory, validations, and more.

In order to create the actual documentation different mechanisms are available. For example you can use a Maven plugin to generate HTML files using markdown templates. Additionally there is a servlet that parses the documentation from the source code and serves it up as REST/JSON. This REST/JSON can then be consumed by custom user interfaces or via the out of the box Swagger UI.

Check out the samples developer.wordnik.com and petstore.swagger.wordnik.com. Similarly to the Social Business Toolkit API Explorer you can not only read the documentation, but also try the REST calls directly.

Last week the involved companies Reverb and Apigee announced the formation of a new working group which will work on the next version 2.0. Read the details.

IBM announced the IBM Cloud marketplace

By Niklas Heidloff, posted on May 19, 2014

At IBM Impact 2014 IBM announced the IBM Cloud marketplace. As Robert LeBlanc wrote in his blog entry the marketplace "will be one of the primary channels through which we deliver IBM as a Service. In addition, we will collaborate with partners from our global ecosystem to deliver hundreds of cloud services for the enterprise."

Watch the video for the announcement in the keynote.



IBM business partners can add their cloud based services. Read the FAQ for details.

"Business partners are selected for inclusion in the IBM Cloud marketplace based on their ability to support enterprise class cloud solutions that complement IBM's leadership in IaaS, PaaS, and Saas. As such, prospective business partners must offer services which run on or are deployable to SoftLayer, which integrate with IBM's BlueMix or patterns PaaS technologies, or which support another of IBM's key cloud offerings, including our many SaaS offerings."
On Friday IBM published a new landing page on developerWorks for IBM Digital Experience developers which includes IBM WebSphere Portal, Web Content Manager, Web Experience Factory and more.

developer.ibm.com/digexp

Similarly to the Social Business Toolkit community, the IBM Portal team uses the best of both worlds: IBM developerWorks and OpenNTF/GitHub.

A landing page for Portal developers is provided on developerWorks and the new IBM developerWorks infrastructure is used as the content management system. Open source samples are contributed to OpenNTF, the open source community for IBM Collaboration Solutions. The OpenNTF organization provides similarly to Apache an infrastructure to host open source projects as well as IP policies and processes to ensure maximal usage of these samples. Projects on OpenNTF can also leverage GitHub as source control repository and system to manage issues and feature requests.

Jonathan Booth and DeAnna Steiner describe in the blog the mission of the new landing page.

"Welcome to the newest place on the web for learning how to develop for IBM Digital Experience! We created this site especially for the growing technical community of developers that are working with the IBM Digital Experience products. ... We’d like this site to be your first stop for developer resources. We’ll share the latest news from the IBM team, post articles on technical topics, and link to key resources. But our primary mission is to provide a central site for sample code and open source extensions for the Digital Experience products."

I like especially the integration of the open source projects from OpenNTF. So far there are 'only' two projects but the intent is to add more over time. The page which displays the open source samples leverages the new OpenNTF API.



A big thank you goes to Jonathan Booth, the driver of this effort, as well as the whole team DeAnna Steiner, Manish Aneja, Martin Lechleider, Jennifer Frischknecht and several more.

New BlueMix RapidApps Demo from IBM Impact

By Niklas Heidloff, posted on May 2, 2014

As I wrote IBM announced BlueMix RapidApps, a runtime and service to allow business developers to build apps rapidly. Yesterday in the day 3 keynote Jerry Cuomo gave an impressive RapidApps demo.

At IBM Impact 2014 IBM announced BlueMix RapidApps Beta.

Check out the announcement and the description of RapidApps. There is also a new IBM developerWorks landing page for RapidApps.

"BlueMix RapidApps is a BlueMix runtime and service whose goal is to broaden the field of participants who can engage in application development by empowering the Business Developer. It is this pool of business developers that we want to tap in support of “80-20-10″ solutions:
- Solve 80% of the business application requirements,
- With 20% of the function with simple, intuitive, visual tools and app platforms,
- By 10X the number of developers developing the apps 10X faster"

More Blog Entries ...

Hi, my name is Niklas Heidloff. I work for IBM as the IBM Collaboration Solutions app dev community advocate. I'm an IBM software architect and OpenNTF director. The blog contains information about IBM Connections, XPages and IBM SmartCloud.

@nheidloff

Disclaimer

The postings on this site are my own and don't necessarily represent my employer IBM's positions, strategies or opinions.