Blog

- December 03, 2014

The rise of API languages

Over the past few years, API languages have emerged. They let you formally describe web APIs and generate useful artifacts from both an API provider and API consumer point of view. Today, the leading languages are API Blueprint, RAML, Swagger, but there is no clear winner at this stage as each tackle the problem from a slightly different angle.  WADL also pioneered API languages, but lost traction over the past years.

API languages

API code editors and Studio inception

To let API developers document APIs or create new ones, each of the leading API languages provides a special web based code editor.

Each of them requires you to choose the API languages you will use moving forward and to learn its syntax in JSON, YAML or MarkDown, then offers additional features such as a visual live preview of the API documentation and sometimes code generation.

When looking at the state of API design languages a year ago to prepare a presentation for APIdays presentation, I identified several issues:

  • 1) API languages available and their editors require you to write API definitions using specific textual syntax to get started,
  • 2) API Blueprint, RAML, Swagger or WADL in the end express a very similar information model on web API definitions,
  • 3) There is no clear API language winner yet, so it is difficult to select one to get your API project started,
  • 4) API design tools should use modern browsers capabilities including local persistence, offline mode and Chrome app packaging.

Restlet StudioToday, after several months of development by our engineering team, we are happy to launch Restlet Studio. It tries to address those issues a provide a new API development experience.

A cross-language visual tool for API design

Restlet Studio provides a web console that lets you visually craft web APIs. No need to learn Swagger or RAML syntaxes in JSON or YAML to get started, Restlet Studio generates them for you in addition to server skeletons to bootstrap your API implementation and client SDKs to facilitate the consumption of your API.

Visual design tab:
Studio - Design tab

Source code tab:
Studio - Swagger tab

As highlighted by Kin Lane (API Evangelist) in his blog post, Restlet Studio provides the first cross API language editor, with initial support for RAML and Swagger.

How is it built?

Restlet Studio runs in modern browsers from http://studio.restlet.com. It can also be installed as a packaged app from the Chrome Store. It works off-line and saves APIs in the local browser data store.

Technically speaking, it is written in Angular/JS, embedding the ACE code editor for syntax coloring. Generation services are powered by APISpark (Restlet API PaaS).

What’s coming next?

Beyond this first preview version, here are the features we are planning to add on our API design tool:

  • 1) import of API languages, facilitating the conversion for example from Swagger 1.2 to Swagger 2.0 or to RAML 0.8,
  • 2) modifiable code views, synced with other views,
  • 3) more code generators, keeping up-to-date with tooling progress in Swagger and RAML communities,
  • 4) support for API Blueprint, API Commons, APIs.json, WADL
  • 5) work and persistence of multiple APIs,
  • 6) sharing of APIs definitions with other API team members or with API users through APISpark online platform,
  • 7) your ideas!

At Restlet, we are excited about the feed-back we got so far from early testers and about the opportunity to shape with the API community a new kind of IDE, web-based and specialized for API creation.

Discuss Restlet Studio in the HackerNews community

CTA_free trial_3

  • Been playing around with the Chrome app, I think it’s great! I am excited that API Blueprint support is coming. My #1 feature request would be .NET/C# support for server skeleton (ASP.NET Web API) and client SDK. I’ve got a lot of experience in these areas would be willing to help with boilerplate code if you’re interested.

  • Guillermo Martínez

    Hello, I’m currently using Swagger and I gotta say that this tool is simply awesome. I can’t wait to see all the Swagger and Raml code generators linked and working here, that’d make this the definitive tool. Keep it up!

  • Dmytro

    What about support of import of Swagger 2.0 API? Is it coming? Can’t find roadmap for feature at your site

    • Guillaume Laforge

      Swagger 2.0 import is definitely on our roadmap. It should actually be available in about a couple of weeks, as it’s obviously an often requested feature. Thanks for your feedback and your patience, and fortunately, this capability will be there very soon!

  • Dmytro

    Thank you!

  • David Fells

    Does Restlet Studio support non-query parameters? I don’t see any options for managing header, form-data, or body based parameters.

    What about importing structures via JSON schema? I’m modeling an existing API with JSON schema available, and a lot of fields – going through the UI one field at a time is not an option.

    Lastly, will there be an ability to have reusable definitions for parameters and responses?

    There are all built into Swagger, so I’m surprised to see them missing.

    • Jerome Louvel

      Hi David, thanks a lot for your feed-back and sorry for missing your comment.

      Restlet Studio supports passing parameters in the body in addition to the path and query parts of the URI.
      For the body, you have to rely on the Representations zone of the UI to define the data structures and their variants (formats/media types supported). Then you can link those representations to the response or request of the relevant HTTP methods via the Input or Output combo boxes. We do not support custom headers as this point but it is a known limitation that we intent to fix ASAP.

      Regarding JSON Schema import, I’ve added an RFE in our system to track this request. We also plan to allow direct editing of the Swagger or RAML source code, so that would become possible to paste/adapt the JSON Schema inline as well.

      Regarding reusable definitions, beside Representations that can be reused across resources and methods, we don’t support yet them at the parameter or response level (similar to traits in RAML or references in Swagger indeed). Definitely another area for improvement that we’d like to see added as well. I’ve entered an RFE as well to track this request.

      Stay tuned as we keep improving Restlet Studio!

  • Brylie Christopher Oxley

    Is the Restlet Studio codebase open-source? If so, where can we view the complete application sourcecode?

    • Jerome Louvel

      Sorry but Restlet Studio is free to use, but isn’t open source. How would you like to extend/customize it? We are thinking about plugins and other ways to make it more open.

  • Big +1 for the JSON Schema import RFE, or even better the direct editing of the RAML source code! In addition, I would *love* to see the JSON Schema data type “enum” (along with “enumNames”) supported by the restlet studio user interface. Any estimates how far this is from today?

  • Thanks Ansgar for the feed-back!

    We should have the Swagger code editor released by the end of this year, but we are still discussing regarding the timing of the RAML editor and JSON Schema import.
    Would Swagger editor work for you in the meanwhile?

    Also, I added a comment to our JSON Schema RFE regarding the support of enum and enumNames data types.

  • rajiv

    Hi
    While importing multi file raml file, the ui throws an error saying the file is invalid
    “The archive does not contain a valid RAML 0.8 definition”.
    I have verified on my end and the raml specification is valid.
    Can you please provide a workaround or something that could be changed so that I can import the raml file

  • rajiv ranjan

    Hi
    While importing multi file raml file, the ui throws an error saying the file is invalid
    “The archive does not contain a valid RAML 0.8 definition”.
    I have verified on my end and the raml specification is valid.
    Can you please provide a workaround or something that could be changed so that I can import the raml file?

  • Hi Rajiv,

    Can you please send your RAML file to support@restlet.com?

    This would help us to quickly provide you a workaround.

    Regards

  • Pingback: 10 years of REST APIs in Java | Restlet - We Know About APIs()

  • Hello,

    I checked the studio, it’s great!
    I generated Restlet Server skeleton, and I’ve find it a little bit limited, i.e. when a representation refers to another one it still generates String property etc. I thought I can find Restlet skeleton template at your fork https://github.com/restlet/swagger-codegen/ , but I can’t. Can you tell me how we can contribute in the restlet stub templates? We are quite interested in it. Thanks!

  • Jerome Louvel

    Hi Mikhail, thanks for the feed-back on our Studio and usage in combination with Framework.
    We currently use our internal templating mechanism to produce the client SDKs and skeletons for Restlet Framework and they are currently closed source.

    If you could list the issues that you have with the current template and post them here or via support@restlet.com that would be great so we can consider them as fast as possible.

    Also, we are considering allowing users to extend the Studio with their own generation templates so they could customize the output. Would that be helpful to you? How far woud you like to customize the generation targets?