Creating Your Own Description.json

If your backend doesn’t support Erstwhile natively, you can create your own description.json file and use that instead.

This file describes how Erstwhile sees an API. You can see an example here for our Todos sample application. We’ve made a JSON Schema-based description.json editor to help you out.

Generally speaking, the description file contains a few core sections:

• Version #: A handy number to tell you what revision you’re at.
• Application Metadata: Includes things like the name, description, and (importantly) the session key header for the API.
• Authentication Section: Erstwhile separates this out so that developers consuming an API can quickly see where the signin and session management methods are.
• Enums: Common lists in the application.
• Entities: These are the models in Erstwhile. Jackpot.

Authentication

When creating your own description.json, you’ll likely need to handle authentication separately, as there are a variety of different schemes for getting access tokens and we can’t account for them all quite yet.

Once you are able to get an access token, please store it in window.localStorage.erstwhileSessionKey.

Using the description.json Editor

Opening the description.json editor, we can start entering the information needed for your local version.

1. Enter a version number. It’s not important what you enter, but it’s required.
2. Enter the application name.
3. Keep the Authentication Scheme as erstwhile-custom-header.
4. Under Header, set the name of the header the backend is expecting for its session key or access token. Assuming you’re storing it in window.localStorage.erstwhileSessionKey, the framework will pass it along.
5. As you’re already handling Authentication yourself, you can skip that section.

Now you have some choices to make.

Erstwhile separates APIs into logical entities. For example, a typical ecommerce site might have entities for Items, Orders, and ShoppingCarts. An Order, in turn, might have methods for submit() and cancel().

Looking at your API, you now have to decide how to assign its various endpoints to different entities, and what to call them.

For each entity do the following:

1. Add the entity under the Entities section.
2. Enter a Unique ID and the two name fields.
3. For each endpoint, add an entry under Methods.
   1. Add the Name. Any logical name should work.
   2. Path (the relative path of the API call, like /api/users/:id/update)
   3. HTTP Method
   4. Function Name (what you’d like to call it when calling from your model, like update(). Without the () though)
   5. Whether or not this endpoint requires authentication

That should be all you need.

Now tab over to the “Description.json Output” tab and copy the JSON in there to a file called /app/config/description.json and save.

From your application root, run npm run models and you should have your new models stored in /app/models/models.js.