How to model custom restriction for an API


#1

Hi community,

I came across RAML when I researched a way to document APIs couple days ago, so I’m pretty new to RAML.

After reading the spec and some tutorials online, I started modeling an existing set of APIs(which is a part of a bigger web services).

Everything was fine(the spec is straight-forward and the Atom API Workbench plugin is of great help) until I tried to apply(model) custom restrictions on the modeled APIs.

As I said before that this set of APIs that I’m modeling is a part of a web services, and they will only be available and accessible if some required feature gets enabled(by calling another set of APIs).

So how am I supposed to model the APIs so that they will not be available if certain feature is disabled?

What I have in my mind:

  • describe this restriction through description of each API
  • describe this restriction through examples of each API

However, I’m not satisfied since the restriction is “first-class” and describing it in description and examples just don’t seem obvious enough.

I’m wondering if there is a better way to achieve what I want?

Thanks!


#2

Hello, Garrio.

I think, you have one of this case:

  1. Your api is not true REST, because it is not stateless.
  2. You are trying to describe the behaviour of your application in RAML. I prefe UML or BPMN for this.

In both cases, you can use description blocks.


#3

Hello,

You can use description, this is an example:

#%RAML 1.0
title: Transfers
description: !include docs/apiDescription.md
version: v0
baseUri: https://www.apis.com/transfers/v0
protocols: [HTTP, HTTPS]
mediaType: [application/json]