The slides from the third Manchester Meetup, this time online. A slide deck explaining the use of RAML and how extensions allow you to separate the code required for service contract or interface and that of the implementation.

1. 31/03/2020: API Design Practices to Accelerate
Development
Manchester MuleSoft Meetup Group

2. All contents © MuleSoft Inc.
Introductions
2
• About Francis Edwards:
– I’ve worked for Saint-Gobain for three years, initially providing integrations between
different corporate systems as well as to external third parties. I’ve replaced numerous
file transfer integrations, automated scripts & exposed APIs to existing or new services for
the Digital Transformation strategy.
– I completed the RAML 0.8 exam without revision, but took a few ‘non’ open book
attempts at the exam following the 2 day API Design course to work out what I needed to
learn.
– I’ve used the Design Centre and Anypoint Exchange to create and publish RAML
specifications and built subsequent implementations using the maven-dependency-plugin
• About Saint-Gobain Building Distribution:
– Saint-Gobain Building Distribution is the company that bring together a number of
suppliers & brands that supply material & tools into the construction industry
– The company is part of the wider Saint-Gobain Group & uses IT infrastructure that is both
within UK datacentres & IT services headquartered in France.

3. All contents © MuleSoft Inc.
RAML Integrating Design with Development
3
• Useful Resources
– There are a number of books that can
help learn API design and RAML
particularly – Manning: The Design of
Web APIs & Undisturbed REST
– API Workbench is a package that can
be installed into ATOM editor
– Design Centre at Anypoint Platform
– The RAML Specification – GitHub
project
– The resources at RAML Org
– The API Design Course from Mulesoft
Training

4. API Design Practices to Accelerate Development
RAML 1.0

5. All contents © MuleSoft Inc.
RAML Integrating Design with Development
5
• Requirement 1 – Anypoint Studio
– The first parts of a RAML definition
can be used to provide configuration
details to developer – this includes
both the http-requester and http-
listener
– Prevents typing errors and assigns
correct testing details
– item definitions aid with using ‘as
:String’ or
Integer.parseInt(message.inboundPr
operties.ID) functions when declaring
values

6. All contents © MuleSoft Inc.
RAML Integrating Design with Development
6
• Requirement 2 – Anypoint Studio
– Flows can be generated with payload
stubs using the imported RAML
specification
– Need to use types with embedded
examples to populate payload stubs

7. All contents © MuleSoft Inc.
RAML Integrating Design with Development
7
• Requirement 3 – Design Centre Console
– Requires to root element to be valid and
ideally have all code in the specification to
render the console
– Requires that securitySchemes defined and a
securedBy element populated by at least null
to provide console functionality
– The documentation element allows a readme
file to be included in the console that can
give instructions for expected behavior and
information in the described resource

8. All contents © MuleSoft Inc.
RAML Integrating Design with Development
8
• Requirement 4 – Anypoint Exchange
– Requires the title element to create the
maven artefact name
– Requires the version to populate the
main version grouping of the published
Anypoint Exchange artefact
– The documentation element is
incorporated within the Anypoint
Exchange artefact and can be cut and
pasted into the artefact page
– baseUri and resource methods auto-
populate in an artefact description pane,
together with instance information

9. All contents © MuleSoft Inc.
RAML Integrating Design with Development
9
• Requirement 5 – API Manager
– The title element is taken from the
title in Anypoint Exchange which
is populated from the original
element
– version required to differentiate
API implementation and produce
unique autodiscovery string
– baseUri required to populate the
location of the API
implementation

10. All contents © MuleSoft Inc.
RAML Integrating Design with Development
10
• Requirement 6 – Service Contract
– Examples data can be included
initially to aid with setting output
payloads, but also provide errors
– Object definitions can be used to
provide meta-data for
transformations
– RAML minimally describes the API
rather than like JSON schemas that
fully describe objects
– Objects are used as input into query-
parms expressions. It is easier to
carry out null checking on JSON
objects than to remember to so this
for each query-param used in a HTTP
requester

11. All contents © MuleSoft Inc.
RAML Integrating Design with Development
11
Demo Time
• Anypoint Design Centre
– This RAML project describes the
access of objects from a resource
and demonstrates the use of
RAML
– My main recommendation being
that rather than specifying
queryParams, that objects
describe instead what can be
searched via the queryString
element

12. See you next time
Please send topic suggestions to the organizer