Create documentation & client SDKs from an API definition


The Restlet Framework provides a tool that extracts the web API definition of your Restlet (or JAX-RS) application and imports it in APISpark to provide documentation and tooling such as generation of client kits.

With this tool, you will be able to create a new APISpark cell and edit it within APISpark.

For this tutorial, we provide you with a Restlet sample API in order to test the Descriptor feature. This fully operational API handles companies and contacts: it can be invoked to add, read, update and delete contacts and companies.


To follow this tutorial, you will need:

  • a web browser,
  • Maven,
  • Git,
  • 20 minutes of your time.

1Retrieve Restlet sample API

We provide you with a Restlet sample API description that allows you to test the Descriptor feature. If you have your own Restlet API, feel free to use it.

  • Install git (if you have not done it yet) to launch a git clone in command line;
  • Launch the command from your development environment. If you are working on Windows, you can use e.g. git shell or git bash.
git clone https://github.com/restlet/restlet-sample-descriptor.git

2Retrieve your credentials

Sign in to APISpark (if you have not done it yet) and retrieve your credentials in the My account page.
Click on your username on top right of the screen and select My account.

Find my credentials

You will find your Username and Secret key in the Tokens section.

My credentials

We will need these credentials to fill in the parameters at introspection launch.

3Launch introspection

Run the introspection code to export the API documentation to APISpark with Maven.
Install Maven (if you have not done it yet) to launch introspection in command line from the restlet-sample-descriptor directory.

mvn test -Pexport-to-apispark -Dapispark.username= -Dapispark.secretkey=

Note: Working on Windows, avoid using git shell or git bash for this operation.

The main method is located in the org.restlet.example.contact.api.ExportToApispark class which source is indicated here in ./src/test/java/org/restlet/example/contact/api/ExportToApispark.java. In order to set your credentials, you can either edit the source code, or use the apispark.username and apispark.secretkey system properties.

Once introspection is completed successfully a similar message displays:

Your Web API descriptor's id is: 123456
Your Web API documentation is accessible at this URL: https://apispark.restlet.com/apis/123456/versions/1/overview

In your APISpark Dashboard, you can see the new Descriptor cell created.

New Descriptor in Dashboard

4Customize API documentation

Once you have imported our sample API documentation in your APISpark Dashboard, feel free to customize it: the application, its resources, methods and beans.

You can customize it either:
- from the APISpark console
- directly from the code

5Share your documentation

If you want to share your documentation with other members or even with your API users, you can make your Descriptor cell public.

From your Dashboard, open your Descriptor cell. Select the Public checkbox and click the Save button.

Make your Descriptor public

You can then communicate the following link to your API users:
https://apispark.restlet.com/apis/\{cell number}/versions/{version number}/overview