I am happy to announce that a new version of API Console is now available. It brings multiple changes and new tooling. Read more to learn what’s new in this release.

API Console is an application to automatically generates documentation for an API from a RAML or Open API definition. It is done by generating an AMF data model thanks to the AMF parser or the “webapi-parser” module. The console is built on top of web platform APIs so it can be easily integrated with every web based application. It comes in two flavors: a stand-alone application and a web component. Depending on your use case you may use either of them.

The stand-alone application allow you to quickly generate documentation for an API and run it on a web server as a separate application. We are providing a CLI tool to generate the application from sources and a Docker image to simplify the deployment. The web component is to be used if you want to integrate the console with an existing application. This requires more setup and development process but allows for the most flexibility.

What’s new in version 6?

API Console is now WCAG compliant. During the development process we put a lot of effort into making sure that the console is accessible for users with disabilities. This version is tested via automated software and via manual testing.

The updated UI implements changes requested by our customers and the community. The navigation has a slightly different structure and now always renders a full path to the resource, even when it exceeds the size of a single line menu item. New examples and annotation widgets makes the UI more user friendly.

The request editor (aka “try it”) has been redesigned to simplify interaction with the API. It now only renders fields that require input from the user to make a successful request. This means, for example, if headers are not defined for an operation then they are not rendered.

With this release we added more security by sanitizing markdown data that are being rendered. Also, user input in the request editor is tested against invalid data.

Improvements to the console

Most improvements are related to performance. The size of the bundle has been reduced almost 4 times and now the bundled API Console weight is ~300KB. This speeds up console rendering time and improves memory footprint.

In the documentation view complex types are now hidden by default. This reduces potential crashes when the documentation has huge type declarations. In previous versions of the console this would lead to tabs crashing. Similarly, huge examples generated for such types are not highlighted by default. Previously it would require the browser to render unreasonable amount of markup that would hang the tab for minutes.

The console’s source has been rewritten to use the latest web standards which puts most of the work to the browser instead of JavaScript. This improves overall experience as the console runs smoothly regardless of the size of the API. The console still works with legacy browsers (down to IE11) with polyfills generated with the bundle.

Developer improvements

Being as close to standards as possible was rule #1 when designing architecture for API Console and the build tools. The console now follows Open WC standards for development and building processes. Application specific code related to the development and building process has been reduced to the minimum.

API Console has its own node module and CLI command to generate a bundle in a CI environment or manually. Besides that with this release we offer a Docker image that has bundled API Console, AMF parser, and a web server with it. As a developer you just need to pass an API project to generate data model from it and run the image on your Kubernetes instance.

Reasons to choose API Console

API Console is and will be in active development as it is one of the core Anypoint platform products while being an open source project. The console is tested in an enterprise environment and runs in both public and private clouds. It fulfills all requirements for an application to run in government’s cloud.

We have experience with building API documentation products supported by several years of development of API Console and other products like Advanced REST Client. We are open to suggestions and over the years we have listened to the voice of the community and our customers. Today we are proud of the final effect of our work and happy to share this experience with the community.

How to get started?

We’ve prepared a few demos with basic use cases for API Console. You can check it out at demo.api-console.io. For developers we have prepared a documentation page at docs.api-console.io.

Try API Console today and give us your feedback. We accept issue reports and feature requests on console’s GitHub page. If you are MuleSoft customer you can contact customer support and gives us your feedback directly.

API Console version 6 is released was originally published in RAML by Example on Medium, where people are continuing the conversation by highlighting and responding to this story.

Last year the CTO of MuleSoft, Uri Sarid, announced that the company is joining the Open API Initiative of the Linux Foundation. This extended MuleSoft’s investment in open specs (RAML) and open source API tooling to also embrace the Open API specification (OAS), as part of its investment in modeling any domain via the Anything Modeling Language (AML) and the open source AML Modeling Framework (AMF). AMF provides automatic interoperability between RAML, which is optimized for modeling HTTP APIs, and OAS, which is a ubiquitous description format for HTTP APIs.

Today I am proud to announce that MuleSoft’s open source API console now supports both RAML and OAS to automatically generate API documentation. This is a part of initiative we started a year ago to add OAS support to Anypoint Platform. Now you can use best in class API documentation tool without worrying about technicalities like API specification format.

This is possible thanks to AML (Anything Modeling Language) and related AMF (AML Modeling Framework). AMF allows to parse RAML and OAS files and produces common data model which is then used in API console to generate the view.

API console comes as a standalone web application and as a set of web components that are highly embeddable in any web environment. This web components — the API components — are open source and can be used to embed API documentation into your existing web page without any limitations. Theming system based on CSS variables allows to style API console according to organization’s corporate style guide. Our developer build tools helps developers to create production ready bundles so the API console can be used across all browsers and web environments. Finally world class design and convenient request editor allows your customers experience the API and learn your products faster.

See our demo page for Google Drive API at https://mulesoft.github.io/api-console/

Build an API portal from your API specification

It is very easy to build an API portal thanks to our CLI tool (Command Line Interface). This section demonstrates how to build an API portal with just few command line commands.

First make sure you have Node.js installed. Open you terminal and type

node --version

This should output something like:

pawel@pawel-pc:~$ node --version
v8.11.2

If it says that the program cannot be found then you have to install Node.js on your machine. To do this follow instructions from https://nodejs.org/en/download/

The next step is to install our CLI tool (no need for sudo command when using Windows)

sudo npm i -g api-console-cli

After few seconds the CLI tool is installed and we can build an API portal. Navigate to your API directory

cd location/of/api

Now run the build command to generate the API. The tool supports build command that has several options. Run api-console build --help to see description for all of them. The most important are:

• -a the location of the API main file
• -t type of the API spec format, it can be RAML 0.8, RAML 1.0, OAS 2.0, or OAS 3.0 (currently in beta)
• -o where to put the result, default to build folder in current directory

Run the final command replacing parameters with your API file name and the type.

api-console build -a api.raml -t "RAML 1.0" -o api-portal

It may take about a minute to build the console. If you run into trouble caused by reaching memory limit, add NODE_OPTIONS=--max_old_space_size=2048 prefix to the command (MacOS, Linux) or set NODE_OPTIONS=--max_old_space_size=2048 on Windows. This prefix sets memory limit for node process to 2GB.

When ready run api-console serve command to see your portal

api-console serve --open api-portal

The --open argument tells the program to open the portal in the default browser.

That’s it! You can now copy generated files to your server and use them to publish your API portal. If you need more advanced build options (like in continuous integration pipeline) you can use our npm module to perform the build.

It is also possible to generate the API Console as a web component and use it to embed API documentation into existing web page. Refer to our docs for more information.

We are happy to hear from you about your experience with API Console and our build tools. Leave us comment, create issue report at mulesoft/api-console repository page or email us at api-console@mulesoft.com.

RAML And OAS Support In API Console was originally published in RAML by Example on Medium, where people are continuing the conversation by highlighting and responding to this story.

Recently, at Chrome Dev Summit, Gray Norton was talking about a new proposal for the web platform (a set of specifications for how browsers render web pages): Layered APIs. It was a great talk about how we can standardise high level APIs using ES6 modules. At the end of the talk Gray asked if anyone had an idea for new primitives or modules for the web. I am answering that call.

At MuleSoft, I create tools to make REST API development easier for developers. I’ve spent the last 3 years creating a set of web components dedicated to API documentation and testing. Another area that interest me is SDKs. The current state of play is that the REST API owner has to produce the documentation for that API and the SDKs for each targeted platform. At Mulesoft, we responded to the first need by creating API Console, a web component which generates documentation for an API. As long as you model your API using RAML or OAS, you can use it to create an API portal or embed the documentation to existing website. As for SDKs, there are tools that generate bundles for different platforms using API spec files. But still, the owner of the API has to publish and document the SDK. I’d like to change this state because I think it is inefficient and because we, as a community, can do better.

What if the browser was able to understand an API and auto-generate the web SDK for a website? In this world all SDKs generated by the browser have unified interface so a web developer has to learn how to use the web SDK once and then only the API structure using API documentation tool. To do this, 3 things would have to happen. First the browser has to get the API definition. We can use the existing <link> element for that.

<link rel="api" type="RAML 1.0" href="api.raml" title="my-api">

I’m proposing a new value for the “rel” attribute: api. It means that the external resource is an API model and should be read as such. The “type” attribute refers to the API definition format. It can be RAML or OAS. Finally “title” would be used to reference the API in the JavaScript interface.

Second thing to do is to parse the API. MuleSoft developed an open source AML (Anything Modeling Language) and AMF (AML Modeling Framework). It provides a common programming interface that lets developers interact with any API specification. AMF can be used to generate a common API model from every API native format.

Finally the browser would generate a JavaScript interface for the API based on the information read from the referenced spec and cache the result locally so next time it skips the downloading and parsing process (that is a very high level description of this part).

API parsing and generating can take some time so the operation has to be asynchronous.

<script>
 await navigator.sdk.ready();
 const sdk = await navigator.sdk.api('my-api');
 const response = await sdk.api.profile.me.get();
 const profile = await response.json();
</script>

The first step is to ensure that all referenced APIs in the head section has been downloaded by the browser. The second step is to parse a specific API and return a reference to the generated SDK. The SDK reflects the structure of the API. It contains the authentication methods, the model definitions, and the structure. For example, the api.profile.me.get() performs a GET request to /profile/me endpoint.

Functions that calls an endpoint can accept the init argument which is the same as the Request object of the Fetch API.

<script>
 const init = {
  headers: {'x-api-key': '....'}, 
  body: JSON.stringify({
    ...
  });
 };
 const response = await sdk.api.todos.post(init);
</script>

To validate user input against the API specification, we could use the validation property of the sdk object.

<script>
 const init = {
  headers: {'x-api-key': '....'}, 
  body: JSON.stringify({
    ...
  });
 };
 const validationResult = sdk.validation.todos.post(init);
 console.log(validationResult.valid);
 console.log(validationResult.messages);
</script>

Most of APIs requires some form of Authentication. This is modeled in the API specification. The browser would fail the request when the user is not Authenticated. The WebSDK also exposes the interface to perform authentication.

<script>
 const config = {
  type: 'OAuth 2.0', 
  grantType: 'implicit', 
  interactive: true, 
  clientId: '....',
  redirectUri: '...'
 };
 if (!sdk.auth.isAuthenticated(config)) {
  await sdk.auth.authenticate(config);
 }
</script>

The isAuthenticated() function checks if the user is authenticated for a given configuration. The configuration structure depends on the authentication type. It requires providing configuration options for the authentication type and node defined in the API definition. Finally it allows to authenticate() the user by performing actions like rendering an auth popup or username/password dialog.

So far this was a brief description of the proposal for a web primitive. It gives a low level API so frameworks and developers can build on top of it. However with the “layered APIs” spec we could do better. Imagine declarative API calls using HTML, e.g.:

<script type="module" src="std:web-sdk"></script>
<script type="module" src="std:web-sdk-authentication"></script>
<script type="module" src="std:web-sdk-request"></script>

<web-sdk api="my-api" id="api">
 <web-sdk-authentication client-id="..." redirect-url="..." id="auth"></web-sdk-authentication>
 <web-sdk-request endpoint="/users/me" method="GET" id="profile"></web-sdk-request>
</web-sdk>

<script type="module">
 api.addEventListener('ready', () => {
  if (!auth.isAuthenticated()) {
    auth.authenticate();
  }
 });

 auth.addEventListener('authenticated-changed', (e) => {
  console.log('User authenticated: ', e.target.authenticated);
 });

profile.addEventListener('api-response', (e) => {
  e.target.response.json()
  .then((profile) => console.log(profile));
 });
</script>

This would import 3 standard modules required for the web API to work: “web-sdk” would be the framework, “web-sdk-authentication” would manage user sessions and “web-sdk-request” would perform API calls. The framework takes care of downloading and parsing the API spec file. Once it is ready, all APIs are available to use. When the user is authenticated, or when the endpoint does not require authorization, the “web-sdk-request” module issues the request to the server. The application listens for an event that indicates the response is ready. The event is dispatched once the API call ends.

This is just a beginning of a web API proposal to the web platform spec. I hope we will be able to start the discussion with Chrome, Firefox, Edge and Safari teams on this proposal. This would change the way we consume APIs in the web platform.

Please leave a comment or feel free to contact me if you are interested in standardizing this API. Meanwhile check the project page for polyfills and technical description: https://github.com/advanced-rest-client/web-sdk

The future of SDKs for the web platform was originally published in RAML by Example on Medium, where people are continuing the conversation by highlighting and responding to this story.

Welcome back!

We left off our discussion with a rather simple model that was somewhat too simple to be useful. It had only simple types and relatively little to help the developer handle changes. Let’s see if we can make this better.

Before we start, we’ll remove the plugin defined in the pom.xml file. Although it’s often simpler to activate the Jackson plugin in the pom.xml file, I’m of the opinion that having to run around the multiple files used in a build to figure out what to do is a bad practice. We’ll be controlling everything RAML from the RAML files. So we will be removing the generateWithTypes tag from our maven file <configuration/>.

<build>
        <plugins>
            <plugin>
                <groupId>org.raml.jaxrs</groupId>
                <artifactId>raml-to-jaxrs-maven-plugin</artifactId>
                <version>3.0.2</version>
                <executions>
                    <execution>
                        <goals>
                            <goal>generate</goal>
                        </goals>
                    </execution>
                </executions>
                <configuration>                    
                   <ramlFile>
                    ${project.build.resources[0].directory}/api.raml
                   </ramlFile>
                  <resourcePackage>
                   org.raml.jaxrs.beertrader.resources
                  </resourcePackage>                              
                  <supportPackage>
                    org.raml.jaxrs.beertrader.support
                  </supportPackage>
                  <modelPackage>
                    org.raml.jaxrs.beertrader.model
                  </modelPackage>
                </configuration>
            </plugin>
        </plugins>
    </build>

We are still generating resource classes and objects, but right now we aren’t generating Jackson annotations. We’ll address this a bit later.

Back to the model. Firstly, we would like our key and reference types to be UUIDs. That’s what we are using in our database system, and it seems to be a good idea to expose this. The problem here is that UUIDs are not part of the RAML specification. All we have are strings. Hmmm.

We’ll start by declaring a type called UUID in our RAML specification. UUIDs are, after all, strings. So we’ll start here.

UUID:
   type: string
   pattern: "[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}"

We could then use this type like so, in a RAML spec:

Beer:
  properties:
   id: UUID

This would be a valid declaration, and the parser handles it correctly. But raml-to-jaxrs still sees it as a string type, and will, by default generate a java.lang.String. If only we could tell it otherwise…

Well, quite obviously, we can. I wouldn’t be typing all of this without a reason.

raml-to-jaxrs allows us to change some of these types (among other things) through a plugin system. The plugin system is activated through RAML annotations. We need to import a RAML Library fragment that defines those annotations in order for raml-to-jaxrs to change its behaviour. In the raml-java-tools project, we’ll find a file called ramltopojo.raml. We can add it to our project and bring it into our spec with:

#%RAML 1.0
title: The BeerTrader api
description: This is the API for the world famous Beer Trader API
version: v1
baseUri:
  value: http://www.beertrader.com/services
protocols: [  HTTP, HTTPS ]
mediaType: [ application/json ]
uses:
  ramltopojo: ramltopojo.raml

This file pulls in plugin support for raml-to-pojo, the library that handles RAML types. We will then activate the core.changeType plugin to tell the code generator to use the java.util.UUID type instead of java.lang.String.

UUID:
    (ramltopojo.types):
      plugins:
        - name: core.changeType
          arguments: [ java.util.UUID ]
      type: string
      pattern: "[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}"

The good thing about this is that Jackson will handle UUIDs properly without any more adjustments, so it’s a pretty simple way of using proper types. Had Jackson not supported the type, we would have had to write a plugin to use annotations or some such. But we don’t, so we won’t this week.

Ok, we’ve moved one step closer to a better model. Huzzah.

Here’s another thing I like to do: have a top-level class for my objects. All my objects will have an ID (think of it like a URN). So let’s build that top class:

Identified:
    (ramltopojo.types):
      plugins:
        - core.makeAbstract
    additionalProperties: false
    properties:
      id: UUID

This object will never travel through the wire: it will only be used as a component of other objects. Therefor we don’t want to build an actual implementation of this object, so we will use another plugin: makeAbstract. This makes it so that only the “interface” half of the object will be generated, without an implementation.

We are getting closer to our target. Well my target at least.

Another thing that annoys me is the manual copying from transfer objects to database objects. The thing is that not all fields should be copied: very often the “plain” properties (strings, number, dates and such) are easy to copy through several libraries. For example, Spring has many methods that allow this.

So we will extract the plain properties of our objects and pull them out to a superinterface. This allows me to reuse this interface in my database objects. I can also use this interface to implement some automatic copying mechanism instead of copying them by hand. That way I can:

1. Make sure that properties are copied from my database objects to my transfer objects and vice-versa.
2. Exclude the more complex members of my objects by not having them in the topmost interface

Let’s just look at the resulting RAML:

InventoryEntryProperties:
    (ramltopojo.types):
      plugins:
        - core.makeAbstract
    additionalProperties: false
    type: Identified
    properties:
      count: integer
      availableCount: integer
InventoryEntry:
    (ramltopojo.types):
      plugins:
        - core.jackson    
    type: InventoryEntryProperties
    additionalProperties: true
    properties:
       beerReference: UUID

In this example, InventoryEntryProperties is the common interface between database objects and the RAML objects. Notice that it is extending type Identified. This will make both our database objects and RAML objects Identified through its “id” property. It has two more simple properties: “count” — which counts the total number of a particular kind of beer — and “availableCount — which counts the bottles that aren’t committed to trades yet. It is also an abstract object.

InventoryEntry inherits from InventoryEntryProperties. First, this is the actual over-the-wire implementation RAML object. For this reason, we need to make sure that the Jackson annotations are added to this generated class. This is added to all the RAML objects that will go over the wire (including the enumerations). Notice that the beerReference property is only accessible through the transfer object: this is because our JPA objects will not be implementing a beerReference property. On the network side, we will use UUIDs, but on the database side we will be using a regular hibernate relationship.

All the objects are built using this model. Our database objects will look like this:

@Entity
public class InventoryObject extends PersistentObject implements InventoryEntryProperties {

    @Basic
    private int count;
    private int availableCount;

    @OneToOne
    private BeerObject beer;
}

With this model we can build fairly simple resource implementations.

@Override
public GetUsersInventoryByUserIdResponse getUsersInventoryByUserId(String userId) {

    // Load from DB.
    List<InventoryObject> inventoryObjects = context
        .createQuery( "from  InventoryObject",
                       InventoryObject.class)
        .getResultList();

    // Copy DB objects to RAML
    List<InventoryEntry> beers =    
        inventoryObjects.stream()
            .map(this::inventoryObjectToInventory)
            .collect(Collectors.toList());

    return GetUsersInventoryByUserIdResponse
               .respond200WithApplicationJson(beers);
}

InventoryEntry inventoryObjectToInventory(InventoryObject db) {
    InventoryEntry inventoryEntry = this.dbToTransfer(db);
    inventoryEntry.setBeerReference(db.getId());

    return inventoryEntry;
}

The “dbToTransfer” method exists and copies the properties. Trust me. Or even better download this phase of the project from https://github.com/jpbelang/BeerTrader/tree/better-model/model.

So we’ve managed to write a RAML model that represents both our business and implementation logic. Sure, it could have been built differently. We could have written a plugin to add JPA annotations to the generated code. Or even simpler, we could have done something using MongoDB and just stored the objects. Or SpringData. Sure. But this is what we did. I like it :-)

Next time, we’ll look into some testing strategies that could leverage the RAML spec.

Using RAML-For-JAX-RS for Brewing (Part II): Building a better model was originally published in RAML by Example on Medium, where people are continuing the conversation by highlighting and responding to this story.

In Part 1, we covered several scenarios in which we defined sets of JSON properties that were either valid or invalid depending on the presence or absence of other properties. In this Part 2, we will focus on validating object properties based on their value and the value of other properties in that object.

Sets of Properties

Sometimes we want objects to have a certain set of properties. Here, we have two properties foo and bar, that may be either respectively equal to Foo and false or to Bar and true.

#%RAML 1.0 DataType

type: object
properties:
  foo: string
  bar: boolean
enum:
  - foo: "Foo"
    bar: false
  - foo: "Bar"
    bar: true

which validates as follows:

{"foo": "Foo", "bar": false} # valid
{"foo": true, "bar": "Bar"} # invalid
{"foo": "Bar"} # invalid
{"foo": "Bar", "bar": true} # valid
{"qux": true} # invalid
{} # invalid

Opposite values

In this scenario, we want the object to have at least two properties foo and bar, that may be either respectively of type string and boolean or boolean and string.

This object can be defined like this:

#%RAML 1.0 Library

Option1:
  properties:
    foo: 
      type: string
      enum: [Foo]
    bar: 
      type: boolean
      enum: [false]
Option2:
  properties:
    foo: 
      type: boolean
      enum: [true]
    bar: 
      type: string
      enum: [Bar]

MyObject: Option1 | Option2

which validates as follows:

{"foo": "Foo", "bar": false} # valid
{"foo": true, "bar": "Bar"} # valid
{"foo": "Bar"} # invalid
{"foo": "Bar", "bar": true} # valid
{"qux": true} # invalid
{} # invalid

Any value

In this scenario, we have an object that must contain the two properies foo and bar, and only those two properties. Their respective value, however, can be of any type.

#%RAML 1.0 DataType

type: object
properties:
  foo: any
  bar: any
additionalProperties: false

which validates as follows:

{"foo": "Foo", "bar": false} # valid
{"foo": true, "bar": "Bar"} # valid
{"foo": "Bar"} # invalid
{"foo": "Bar", "bar": true} # valid
{"qux": true} # invalid
{} # invalid

Conditional JSON properties (Part 2) was originally published in RAML by Example on Medium, where people are continuing the conversation by highlighting and responding to this story.

One of the most important aspect of designing Web APIs is modeling its data layer. The data layer can take different shapes and it can be found at different levels of the API: URI parameters, query parameters, request and response headers, request and response bodies.

When modeling a JSON object — the most common format for transmitting data these days — we may want sets of properties to be either valid or invalid depending on the presence or the absence of other properties.

Let’s take a look at different scenarios.

All and only defined properties

This is the most common one. We want an object to contain all and only defined properties, here foo and bar. These properties must be respectivly string and boolean.

This object can be defined like this:

#%RAML 1.0 DataType

additionalProperties: false
properties:
  foo: string
  bar: boolean

which validates as follows:

{"foo": "lorem ipsum", "bar": false} # valid
{"foo": true, "bar": false} # invalid
{"foo": "lorem ipsum"} # invalid
{"bar": "lorem ipsum", "foo": false} # invalid
{"qux": 1} # invalid
{} # invalid

Any of either defined or undefined properties

In some cases, we want to allow an object to contain any number of properties. However, if some specific properties are defined, here foo and bar, we want those properties to be of a certain type.

This object can be defined like this:

#%RAML 1.0 DataType

properties:
  foo?: string
  bar?: boolean

which validates as follows:

{"foo": "lorem ipsum", "bar": false} # valid
{"foo": true, "bar": false} # invalid
{"foo": "lorem ipsum"} # valid
{"bar": "lorem ipsum", "foo": false} # invalid
{"qux": 1} # valid
{"foo": null, "bar": null} # invalid
{} # valid

Making sure at least one property is defined

Building on the previous scenario, we want all of the above conditions and we also want to ensure at least one property is defined.

This object can be defined like this:

#%RAML 1.0 DataType

minProperties: 1
properties:
  foo?: string
  bar?: boolean

which validates as follows:

{"foo": "lorem ipsum", "bar": false} # valid
{"foo": true, "bar": false} # invalid
{"foo": "lorem ipsum"} # valid
{"bar": "lorem ipsum", "foo": false} # invalid
{"qux": 1} # valid
{} # invalid

Any of only defined properties

Building again on the previous scenario, we want all of the above defined conditions but we also want to restrict the properties to only the ones defined.

This object can be defined like this:

#%RAML 1.0 DataType

additionalProperties: false
minProperties: 1
properties:
  foo?: string
  bar?: boolean

which validates as follows:

{"foo": "lorem ipsum", "bar": false} # valid
{"foo": true, "bar": false} # invalid
{"foo": "lorem ipsum"} # valid
{"bar": "lorem ipsum", "foo": false} # invalid
{"qux": 1} # invalid
{} # invalid

Any defined properties, any defined types

Here, we want the object to contain at least one property, either foo or bar, but no additional properties. Either property can be string or boolean.

This object can be defined like this:

#%RAML 1.0 DataType

minProperties: 1
properties:
  /^(foo|bar)$/: string | boolean

which is equivalent to:

#%RAML 1.0 DataType

additionalProperties: false
minProperties: 1
properties:
  foo?: string | boolean
  bar?: string | boolean

and which validates as follows:

{"foo": "lorem ipsum", "bar": false} # valid
{"foo": true, "bar": false} # valid
{"foo": "lorem ipsum"} # valid
{"bar": "lorem ipsum", "foo": false} # valid
{"qux": 1} # invalid
{} # invalid

Mirror properties

In this scenario, we want the object to have at least two properties foo and bar, which may be either string or boolean, but never at the same time.

This object can be defined like this:

#%RAML 1.0 Library

Option1:
  properties:
    foo: string
    bar: boolean
Option2:
  properties:
    foo: boolean
    bar: string
MyObject: Option1 | Option2

which validates as follows:

{"foo": "lorem ipsum", "bar": false} # valid
{"foo": true, "bar": false} # invalid
{"foo": "lorem ipsum"} # invalid
{"bar": "lorem ipsum", "foo": false} # valid
{"qux": 1} # invalid
{} # invalid

Conditional JSON properties (Part 1) was originally published in RAML by Example on Medium, where people are continuing the conversation by highlighting and responding to this story.

raml-javascript-generator is a tool that generates JavaScript API clients from RAML API definitions. It takes a RAML file as input and outputs a NPM package.

Let’s start by installing raml-javascript-generator:

$ npm install raml-javascript-generator -g

We now need a RAML file, let’s use the world-music-api from the raml-org/raml-examples repository. At this point, we can either reference a local RAML file or point to a remote one using an URL:

$ raml-javascript-generator https://raw.githubusercontent.com/raml-org/raml-examples/e91308b/others/world-music-api/api.raml -o world-music-api

Let’s take a closer look inside:

$ cd world-music-api/
$ ls -1 ./
INSTALL.md
README.md
index.js
package.json

The result is an installable NPM package with all its dependencies defined in package.json.

$ cat package.json | jq .dependencies
{
  "client-oauth2": "^2.1.0",
  "xtend": "^4.0.1",
  "request-promise": "^4.2.2",
  "request": "^2.34",
  "setprototypeof": "^1.0.1",
  "query-string": "^5.0.0"
}

It also generates a README with basic usage instructions. Let's take a look at some of those instructions:

$ grep -o '#### `.*' README.md 
#### `api.get([query, [options]])`
#### `api.post([body, [options]])`
#### `entry.post([body, [options]])`
#### `entry.get([query, [options]])`
#### `songs.get([query, [options]])`
#### `songs.post([body, [options]])`
#### `songs.songId({ songId }).get([query, [options]])`

Great! Now, we can install the generated library:

$ npm install

and use it in our JavaScript code.

But before playing further, we’ll need to have an API backend running. We’ll use osprey-mock-service for that (don't forget to check-out this osprey-mock-service post):

$ osprey-mock-service -f https://raw.githubusercontent.com/raml-org/raml-examples/e91308b/others/world-music-api/api.raml -p 1234
Mock service running at http://localhost:1234

Now that we have an API backend running, we can query using our world-music-api library:

# test.js
const WorldMusicAPI = require('.')
const client = new WorldMusicAPI({baseUri: 'http://localhost:1234/v1'})

client.songs.songId({'songId': 1}).get().then((response) => {
  console.log(response.body)
})

Then, running this snippet will output:

node test.js 
{ title: 'My Song', length: 12 }

raml-javascript-generator Quick Start was originally published in RAML by Example on Medium, where people are continuing the conversation by highlighting and responding to this story.

raml-cop is a command-line tool for validating RAML files. It supports both RAML 0.8 and 1.0. It can validate included files as well as RAML 1.0 Fragments.

Let’s give it a try. We’ll start by installing raml-cop globally so that it's permanently availble in the terminal:

$ npm i -g raml-cop

Now, let’s download a simple RAML example:

$ curl -o api.raml https://raw.githubusercontent.com/raml-org/raml-examples/master/typesystem/simple.raml

And let’s validate it:

$ raml-cop api.raml
[api.raml] VALID

Now, let’s make that RAML file invalid by removing its first line:

$ tail -n +2 api.raml > api-invalid.raml

and let’s validate that invalid RAML again:

$ raml-cop api-invalid.raml
[api-invalid.raml] ERROR Invalid first line. A RAML document is expected to start with '#%RAML <version> <?fragment type>'.

raml-cop Quick Start was originally published in RAML by Example on Medium, where people are continuing the conversation by highlighting and responding to this story.

This is a tutorial on how to use raml-for-jaxrs to develop a real-life application. We will try to cover every aspect of application development and build on our application base. I’ll break this down into sections. They’ll be clear, don’t worry.

It seems to me that everyone and their brother-in-law is brewing beer these days. All sorts of beers (mostly IPAs, honestly) being made off different recipes and some rather original ideas. It seems that beer has brought out the artist in a lot of people.

And artists like to show off their stuff. And show off they do. They’ll bring their home-brewed stuff to parties and other types of social gatherings and share. Which is all good, until the sheer volume of their production creates a backlog of bottles that will soon overrun your house. Or at least your basement.

Well, there’s BeerTrader to the rescue. BeerTrader will allow you to both keep an inventory of your brews and allow you to setup trades with other users of the site, allowing you to rotate your overstock into different types of beer, just so you don’t go nuts drinking that apricot based recipe that you thought would turn out great.

So the first iteration of the server will be just about useless: it will just be a server that takes messages, translates it to DB objects and persists it in the database. That’s it: no great model, no real security, no real testing. We will then try to organize our data better, add validation, add security features and such. At the end, we should have a good simple implementation of our server.

Stuff you need to know

Well, the first thing you need to know is RAML 1.0. No deep knowledge required. I don’t have a deep knowledge myself and I probably refer to the spec more often than I should. You also probably need to know about JAX-RS. Again, nothing complicated. There will be some hibernate stuff, but we won’t get into the nitty gritty. And the project will be bootstrapped with spring-boot, because it’s magical.

I’m guessing that you’d like to know where the server code is right now: well it’s here. The master branch contains the finished code for our tutorial. I’ll be referring to it all through this post.

The Setup

We are going to be using maven to setup our project. There will be two submodules: the model submodule, where the model objects and JAX-RS stubs will be generated. This is the part we should NOT be editing. In fact, the only files we’ll be editing are the api.raml and the maven POM files.

The second module is the server module, where everything else lives: Spring, hibernate and its objects and our implementations of the JAX-RS interface. The database schema is automatically built and stored in memory (using HSQLDB).

BeerTrader
 model
   src
    main
      resources
        api.raml          <-- Our RAML model
   pom.xml                <-- The pom.xml using raml-for-jaxrs
 server
   src
     main
      java
        org
          raml
            jaxrs
              beertrader
                data      <-- Database model
                resources <-- implementations of JAX-RS
                spring    <-- String configuration for resources
     resources
       META-INF
         persistence.xml  <-- Database configuration
    pom.xml

Our model objects

For now, we’ll create a very simple REST model. Objects will only use simple properties and use no form of inheritance. We will be improving the model as we go.

All our objects will have an ID.

The first object in the model is, as in most systems, the User. It’s the classic name and email kind. Nothing particularly innovative.

User:
  properties:
    id: string
    name: string

We have two enumerations on how we define the kind of beer being used. Two different YAML list styles giving the same results. By the way, we’ll be storing these enumerations straight into the database. They are in fact shared between both the messages and database objects.

BeerType:
    enum: [ALE, STOUT, LAGER, PORTER, MALTS, OTHER]
BeerStyle:
    enum:
      - AMBER
      - BLOND
      - BROWN
      - CREAM
      - DARK
      - FRUIT
      - GOLDEN
      - HONEY
      - IPA
      - LIGHT
      - LIME
      - PALE
      - PILSNER
      - STRONG
      - RED
      - PILSNER
      - WHEAT
      - OTHER

We then have the Beer object. This object uses our two enumerations by referring to BeerType and BeerStyle.

Beer:
  properties:
    id: string
    name: string
    description: string
    type: BeerType
    style: BeerStyle

The next object is the InventoryEntry object. This object essentially contains a count for a given beer. The beerReference property contains the ID value of the counted beer.

InventoryEntry:
  properties:
    id: string
    beerReference: string
    count: integer
    availableCount: integer

Finally, a Trade object. A very flat data structure containing “from” and “to” components. We have two references for the beers being traded matched to the users trading them away. We are still using the string IDs as references. Not much to see here either. We’ll make everything better in the next instalment.

Trade:
  properties:
    id: string
    fromUserReference: string
    fromBeerReference: string
    fromCount: integer
    toUserReference: string
    toBeerReference: string
    toCount: integer

Our resources

The resources used in our application will start straightforward. The only thing I will do here is separate them so that I have different Java classes. Should I model everything in one tree, it would create only one large Java interface to implement. That would be rather unwieldy structure to use.

So we will break our application down along the lines of operations on our model objects. They will be built in the expected collection/item fashion: the URI “/somethings” will list a collection of objects where we create objects, and “/somethings/{id}” will allow us to play with a specific object.

My first draft started as something like this:

/users:
  get:
    responses:
      200:
        body:
          application/json: User[]
  post:
    body:
      application/json: User
    responses:
      201:
        body:
          application/json: User
  /{userId}:
    get:
      responses:
        200:
          body:
            application/json: User
        404:
    delete:
      responses:
        200:
        404:
    put:
      body:
        application/json: User
      responses:
        200:
        404:
/users/{userId}/inventory:
  get:
    responses:
      200:
        body:
          application/json: InventoryEntry[]
  post:
    body:
      application/json: InventoryEntry
    responses:
      201:
        body:
          application/json: InventoryEntry
  /{entryId}:
    get:
      responses:
        200:
          body:
            application/json: InventoryEntry
        404:
    delete:
      responses:
        200:
        404:
    put:
      body:
        application/json: InventoryEntry
      responses:
        200:
        404:
/users/{userId}/beers:
  get:
    responses:
      200:
        body:
          application/json: Beer[]
  post:
    body:
      application/json: Beer
    responses:
      201:
        body:
          application/json: Beer
  /{entryId}:
    get:
      responses:
        200:
          body:
            application/json: Beer
        404:
    delete:
      responses:
        200:
        404:
    put:
      body:
        application/json: Beer
      responses:
        200:
        404:

However, this seems repetitive. So we’ll reach into the shallow part of our RAML bag of tricks and use a resourceType to save repetition. ResourceTypes can be used like templates. They save typing.

resourceTypes:
  collection:
    get:
      responses:
        200:
          body:
            application/json: <<targetType>>[]
    post:
      body:
        application/json: <<targetType>>
      responses:
        201:
          headers:
            Location: string
          body:
            application/json: <<targetType>>  item:
    get:
      responses:
        200:
          body:
            application/json: <<itemType>>
        404:
    delete:
      responses:
        200:
        404:
    put:
      body:
        application/json: <<itemType>>
      responses:
        200:
        404:

Our resources now becomes:

/users:
  type: { collection: { targetType: User } }
  /{userId}:
    type: { item: { itemType: User } }

/users/{userId}/inventory:
  type: { collection: { targetType: InventoryEntry } }
  /{entryId}:
    type: { item: { itemType: InventoryEntry } }

/users/{userId}/beers:
  type: { collection: { targetType: Beer } }
  /{entryId}:
    type: { item: { itemType: Beer } }

/users/{userId}/trades:
  type: { collection: { targetType: Trade } }
  /{tradeId}:
    type: { item: { itemType: Trade } }

So we now have a RAML specification. From this, we’ll generate our objects and JAX-RS stubs. We’ll be using maven. To do this, all we need to set up is the appropriate maven plugin.

<build>
        <plugins>
            <plugin>
                <groupId>org.raml.jaxrs</groupId>
                <artifactId>raml-to-jaxrs-maven-plugin</artifactId>
                <version>3.0.2</version>
                <executions>
                    <execution>
                        <goals>
                            <goal>generate</goal>
                        </goals>
                    </execution>
                </executions>
                <configuration>
                    <ramlFile>
                    ${project.build.resources[0].directory}/api.raml
                    </ramlFile>
                    <resourcePackage>org.raml.jaxrs.beertrader.resources</resourcePackage>
                    <supportPackage>org.raml.jaxrs.beertrader.support</supportPackage>
                    <modelPackage>org.raml.jaxrs.beertrader.model</modelPackage>
                    <generateTypesWith>
                        <value>jackson2</value>
                    </generateTypesWith>
                </configuration>
            </plugin>
       </plugins>
</build>

We separate the generated code into three packages: the model package will contain the message objects, the resources package will contain our JAX-RS resource stubs, and finally the support package which is for somewhat internal raml-for-jaxrs usage.

The other important setup is the generateTypesWith section: here we set up plugins to the object and resource generation processes. It’s the simplest of three ways of setting up plugins. It’s also the least flexible: it applies to everything in the RAML spec. The only one we have in there for now is jackson2, which will generate Jackson 2 annotations on our objects for marshalling and unmarshalling.

Once this is done, we can go into our project directory and create the model.

Biggly:BeerTrader jpbelang$ cd model
Biggly:model jpbelang$ mvn clean install
[INFO] Scanning for projects...
[INFO] 
[INFO] -------------------------------------------------------------
[INFO] Building model 1.0-SNAPSHOT
[INFO] -------------------------------------------------------------

This will generate the code in the target/generated-sources/raml-to-jaxrs directory. Go ahead, check it out.

The implementation

We will now implement our interfaces and bridge the calls to the database. Before we get into that though, I’d like to state that I’m not going to explain much of Spring, and I’m asking you to just believe in magic when it comes to injection. It works and it makes our life simpler.

Ok, so let’s look at UsersImpl. First thing we’ll have to do is implement the stub interface. Forces us to implement something that supports the resources in our RAML specification.

import org.raml.jaxrs.beertrader.data.UserObject;
import org.raml.jaxrs.beertrader.model.User;
import org.raml.jaxrs.beertrader.model.UserImpl;
import org.raml.jaxrs.beertrader.resources.Users;
import org.springframework.stereotype.Component;

import javax.inject.Inject;
import javax.persistence.EntityManager;
import javax.persistence.NoResultException;
import javax.transaction.Transactional;
import java.util.List;
import java.util.stream.Collectors;

@Component
@Transactional
public class UsersImpl implements Users {

final private EntityManager context;

@Inject
    public UsersImpl(EntityManager context) {
        this.context = context;
    }

@Override
    public GetUsersResponse getUsers() {

List<UserObject> dbUsers = context
          .createQuery("from UserObject ", UserObject.class)
          .getResultList();
       List<User> users = dbUsers
          .stream()
          .map(UsersImpl::userObjectToUser)
          .collect(Collectors.toList());

return GetUsersResponse
         .respond200WithApplicationJson(users);
    }
// ...

We don’t return simple JAX-RS Responses. Returned responses must conform to what is in the RAML specification. The interface makes it simple to return the correct return codes and headers. So you should use it respectfully: don’t fool around with headers and such to break your own RAML spec.

So in this method, we fetch users from the database, transform them into transfer objects and return them with a RAML safe response.

A quick simple run

We can run the server in one of two ways: running from the IDE or from the command line. Either way, we will need to run the main class (in server/src/main/java/org/raml/jaxrs/beertrader/Main.java). To run from maven, from the server directory:

java -jar target/server-1.0-SNAPSHOT.jar

You should also be able to run it from your IDE.

POST /services/users HTTP/1.1
Host: localhost:8080
Content-Type: application/json
Cache-Control: no-cache

{
 "name": "JP Belanger",
 "email": "jp@fun.com"
}

returning the response:

HTTP/1.1 201 Created
Content-Length: 43
Content-Type: application/json
Date: Sun, 27 May 2018 18:00:13 GMT
Location: http://localhost:8080/services/users/084586f3-3f22-4248-901a-522da0252fda

{
    "name": "JP Belanger",
    "email": "jp@fun.com"
}

So that’s it: this is a simple version of a currently simple service. We will be adding to it shortly.

Using RAML-For-JAX-RS for Brewing (Part I) was originally published in RAML by Example on Medium, where people are continuing the conversation by highlighting and responding to this story.

This is an introduction to oas-raml-converter. oas-raml-converter is a command line tool that helps convert to and from RAML and OAS.

Let’s begin by installing oas-raml-converter as a command-line tool:

$ npm i -g oas-raml-converter

and let’s also grab a RAML file:

$ curl https://raw.githubusercontent.com/raml-org/raml-examples/master/typesystem/simple.raml -o api.raml

Now, we can convert it from RAML 1.0 to OAS 2.0 with the following command:

$ oas-raml-converter --from RAML --to OAS20 ./api.raml > api.oas2

the output will look like this:

and we can even convert that same API Spec from RAML 1.0 to OAS 3.0 with:

$ oas-raml-converter --from RAML --to OAS30 ./api.raml > api.oas3

Using oas-raml-converter as a NodeJS library

oas-raml-converter can also be used as a library! This is particularly useful when processing either the input or the output. Let's see how it works.

In this scenario, I’ll use oas-raml-converter to convert from RAML 1.0 to OAS 2.0, and then, use yamljs to convert the output to the YAML syntax.

I’ll start by initializing my project and installing both libraries:

$ npm init --yes
(...)

$ npm install --save oas-raml-converter yamljs
(...)

then, let’s create an index.js file with the following code:

and then run with node . which will output my API Spec in OAS 2.0 format with the YAML syntax:

oas-raml-converter Quick Start was originally published in RAML by Example on Medium, where people are continuing the conversation by highlighting and responding to this story.