Home

About RSD

RSD (Remote Service Description) is a set of DSLs to define your (web-)APIs, document them and generate source code.

Currently the following RSD-DSLs are available:

• RSD - the main language to define your domain types and services
• RRSD - language to expose your services as REST-Endpoints

Sample

simple-sample.rsd

patchable record Person {
  @id id: string

  firstname: string
  lastname: string
  shoesize?: double
}

error NotFound;

service Person {
  operation get(key: string): Person throws NotFound;
  operation list(): Person[];
  operation create(firstname: string, lastname: string, shoesize?: double): Person;
  operation update(key: string, @patch personChange: Person);
  operation delete(key: string);
}

sample.rrsd

resource Person at '/api/person' {
  GET get at '${key}' => {
    200
    404: NotFound
  }
  GET list at ''
  POST create at '' => {
    201
  }
  PATCH update at '${key}' => {
    204
  }
  DELETE delete at '${key}' => {
    200
    404: NotFound
  }
}

OpenAPI and RSD

RSD is much more opinionated than OpenAPI who has much more freedom, so you can not express everything in RSD one can express in OpenAPI. This freedom although comes with a price. Handcrafting OpenAPI-Spec is fairly painful and it is next to impossible to grasp from a give OpenAPI-Specfication how the types and services look like (see the above sample as OpenAPI).

As OpenAPI is more or less an industry standard there is the possibility to generate OpenAPI-Specifications from your RSD files.

Typespec and RSD

RSD and Typespec are fairly similar the main difference is that RSD makes a clean split between the data-type/service definition (in .rsd-file) and exposing it eg as a REST-Resource (in an .rrsd-File). The main driver for splitting things up in the 2 files (and 2 seperate languages) is that we think is that it vastly improves readability.