Hackolade Tutorial - part 12 - Create a REST API model

Hackolade Tutorial
Part 12 - Create a REST API model
Copyright © 2016-2023 Hackolade 1

In this Tutorial
• How to visually design a schema-centric REST API, using the Swagger
or OpenAPI specification
• No need to know the Swagger/OpenAPI syntax
• but need to know the features...
• Fits really well with API-first and design-first processes
• Especially when combined with NoSQL data stores: access patterns and APIs
are very often aligned – and therefore so is their model
• Helps to understand existing APIs: visual representation of
Swagger/OpenAPI files
• Hackolade Studio will reverse engineer these files into a data model
• Focusing on OpenAPI – principles also apply to Swagger

Example: URL shortener
• a user creates an entry based on a full URL, and receives a
short slug generated by the service
• any system can send a slug and get back the full URL.
• The example is inspired by Shorty, an existing service

Output: visual model for the API
Copyright © 2016-2023 Hackolade

Output: generated corresponding API file

Design the API
• Put yourself in the shoes of the consumer & make it easy to
understand and navigate
• Start with a sequence diagram:
First process: create entry based on full URL,
Receive short slug generated by service
Second process: Send a slug, get back the full URL

Sequence is important!
• Many Swagger tutorials start with info, then paths, then components
• We recommend that you start with the foundation: schema describing the
structure of the service contract between producer and consumer
• Process:
1. create reusable components
• schema for the exchange
• request body to submit a long URL, using the schema
• parameter to fetch the full URL from a slug
• responses
• returning the generated slug (200 - OK) using the schema
• returning an error message, reusable for different kinds of errors
• an OAuth2 security scheme (can be done later)
2. create resources with requests and responses
3. add endpoint, tags, and metadata information, plus color coding of responses
4. generate the OpenAPI documentation file, with API testing

Create reusable components
1. Schema for the exchange
• URL: for happy flow exchange
• LongURL
• Slug
• Error: for error messages
• StatusCode
• Message

2. Request body to submit a long URL

3. Parameter to fetch a full URL from a previously generated slug

4. A couple of responses
Create a response structure Template gets created
Start with 200 - OK The structure now references the component schema:

5. A security schema

Create resources with requests and responses
• Assemble the reusable components in resource paths

• Add a request
POST: submit a full URL and/or a custom slug

• Assign a tag
• Work in the dedicated tab

• different ways to build a request, all represented in the template.

• Add a response

• Work in the dedicated tab

• 400: did not confirm to schema
• 403: forbidden request that did not provide credentials

Resulting API

Second use case

Finishing touches
• Metadata: server endpoints, tag descriptions, links to documentation

Generate the OpenAPI documentation file

API creation debate
• Code-first vs. design-first?
• Design-first helps you think through all the details, discuss
alternatives with stakeholders, evaluate impacts, etc.
• Advantages = Lower TCO, higher quality, easier evolution, and…
quicker Time to Value!
• Reduces the risk of rework!
• See this article by Smartbear, creators of Swagger

Reading material
• See Hackolade online documentation
• The Hackolade Blog
• This excellent new book:
MongoDB Data Modeling & Schema Design
• Many of the principles in the book are related to query
driven modeling based on access patterns!
• Hackolade’s on social media: LinkedIn page, Twitter page
• Download Hackolade studio for free

Questions?
Answers!

Hackolade Tutorial - part 12 - Create a REST API model

More Related Content

Similar to Hackolade Tutorial - part 12 - Create a REST API model

More from PascalDesmarets1

Recently uploaded

Hackolade Tutorial - part 12 - Create a REST API model