Hackolade Tutorial - part 12 - Create a REST API model

•

0 gostou•58 visualizações

By the end of this tutorial, you will master how to create a model for REST APIs using Swagger or OpenAPI specification.

Tecnologia

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
Copyright © 2016-2023 Hackolade 2

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
Copyright © 2016-2023 Hackolade 3

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

Output: generated corresponding API file
Copyright © 2016-2023 Hackolade 5

Design the API
• Put yourself in the shoes of the consumer & make it easy to
understand and navigate
• Start with a sequence diagram:
Copyright © 2016-2023 Hackolade 6
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
Copyright © 2016-2023 Hackolade 7

Create reusable components
1. Schema for the exchange
• URL: for happy flow exchange
• LongURL
• Slug
• Error: for error messages
• StatusCode
• Message
Copyright © 2016-2023 Hackolade 8

Create reusable components
2. Request body to submit a long URL
Copyright © 2016-2023 Hackolade 9

Create reusable components
3. Parameter to fetch a full URL from a previously generated slug
Copyright © 2016-2023 Hackolade 10

Create reusable components
4. A couple of responses
Copyright © 2016-2023 Hackolade 11
Create a response structure Template gets created
Start with 200 - OK The structure now references the component schema:

Create reusable components
5. A security schema
Copyright © 2016-2023 Hackolade 12

Create resources with requests and responses
• Assemble the reusable components in resource paths
Copyright © 2016-2023 Hackolade 13

Create resources with requests and responses
• Add a request
Copyright © 2016-2023 Hackolade 14
POST: submit a full URL and/or a custom slug

Create resources with requests and responses
• Assign a tag
• Work in the dedicated tab
Copyright © 2016-2023 Hackolade 15

Create resources with requests and responses
• different ways to build a request, all represented in the template.
Copyright © 2016-2023 Hackolade 16

Create resources with requests and responses
• Add a response
Copyright © 2016-2023 Hackolade 17

Create resources with requests and responses
• Work in the dedicated tab
Copyright © 2016-2023 Hackolade 18

Create resources with requests and responses
• 400: did not confirm to schema
• 403: forbidden request that did not provide credentials
Copyright © 2016-2023 Hackolade 19

Resulting API
Copyright © 2016-2023 Hackolade 20

Second use case
Copyright © 2016-2023 Hackolade 21

Finishing touches
• Metadata: server endpoints, tag descriptions, links to documentation
Copyright © 2016-2023 Hackolade 22

Generate the OpenAPI documentation file
Copyright © 2016-2023 Hackolade 23

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
Copyright © 2016-2023 Hackolade 24

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
Copyright © 2016-2023 Hackolade 25

Questions?
Answers!
Copyright © 2016-2023 Hackolade 26

Recomendados

The 12 facets of the OpenAPI standard.pdf

Cisco DevNet

Tutorial Expert How-To - Command Line Interface (CLI)

PascalDesmarets1

18 facets of the OpenAPI specification - Cisco Live US 2023

Cisco DevNet

the 12 facets of OpenAPI

Cisco DevNet

Using Google App Engine Python

Akshay Mathur

Hackolade Tutorial - part 9 - Export or forward-engineer.pdf

PascalDesmarets1

OpenAPI 3.0, And What It Means for the Future of Swagger

SmartBear

apidays Paris 2022 - The 12 Facets of the OpenAPI Specification, Steve Sfartz...

apidays

IBM Integration Bus and REST APIs - Sanjay Nagchowdhury

Karen Broughton-Mabbitt

With the growing interest in the API economy, IBM Integration Bus (IIB) has provided many recent enhancements in the area of REST APIs and JSON support. This session will discuss how to create an IIB REST API, either from scratch or starting from a Swagger (OpenAPI specification) document. We will also cover the new JSON Schema support for the Graphical Data Mapper, and the new REST Request node for calling REST APIs from IIB, which can be easily configured by drag-and-drop. Easy integration of IIB Rest APIs with an API Connect catalog is also possible, from both the IIB Toolkit and the IIB Web UI. We will talk through these new capabilities and how they relate to IBM's Application Integration Suite (AIS) solution.

Introduction to SignalR

University of Hawai‘i at Mānoa

Mvc 4.0

Ram Ayyalaraju

James Higginbotham - API Design

John Zozzaro

(ATS6-PLAT04) Query service

BIOVIA

The Query Service is the new platform solution for querying a variety of data sources. The goal of Query Service is that administrators can configure a metadata description of the data source that can then be used by end users without detailed knowledge of the underlying data source. This session explains how to configure Query Service data sources and use them with the RESTful API or component collection.

Logic apps and PowerApps - Integrate across your APIs

Sriram Hariharan

Lessons learned on the Azure API Stewardship Journey.pptx

apidays

apidays LIVE Singapore 2022: Digitising at scale with APIs April 20 & 21, 2022 Lessons learned on the Azure API Stewardship Journey Adrian Hall, Principal Product Manager at Microsoft ------------ Check out our conferences at https://www.apidays.global/ Do you want to sponsor or talk at one of our conferences? https://apidays.typeform.com/to/ILJeAaV8 Learn more on APIscene, the global media made by the community for the community: https://www.apiscene.io Explore the API ecosystem with the API Landscape: https://apilandscape.apiscene.io/ Deep dive into the API industry with our reports: https://www.apidays.global/industry-reports/ Subscribe to our global newsletter: https://apidays.typeform.com/to/i1MPEW

Tutorial Workgroup - Model versioning and collaboration

PascalDesmarets1

Hackolade Studio has native integration with Git repositories to provide state-of-the-art collaboration, versioning, branching, conflict resolution, peer review workflows, change tracking and traceability. Mostly, it allows to co-locate data models and schemas with application code, and further integrate with DevOps CI/CD pipelines as part of our vision for Metadata-as-Code. Co-located application code and data models provide the single source-of-truth for business and technical stakeholders.

Code for Startup MVP (Ruby on Rails) Session 1

Henry S

Scribe online 03 scribe online cdk and api overview

Scribe Software Corp.

CC Technology Summit 3 Update

Nathan Yergler

Brushing skills on SignalR for ASP.NET developers

ONE BCG

Let’s take a quick peek at SignalR and how we use it. SignalR is an open-source library available in ASP.NET, to help developers add real-time features in web applications and more. Chat is the most common application that you can think of, there is a lot more you can do. SignalR can be used to add any sort of “real-time” web functionality like dashboards, collaborative tools that require simultaneous editing of documents, job progress updates, and real-time forms. It can enable completely new types of web applications that need high-frequency updates from the server. One of the most common examples is real-time gaming.

Apidays Paris 2023 - Managing OpenAPI Documents at Scale, Stéve Sfartz, Cisco

apidays

Apidays Paris 2023 - Software and APIs for Smart, Sustainable and Sovereign Societies December 6, 7 & 8, 2023 Managing OpenAPI Documents at Scale Stéve Sfartz, Principal Architect, API at Cisco ------ Check out our conferences at https://www.apidays.global/ Do you want to sponsor or talk at one of our conferences? https://apidays.typeform.com/to/ILJeAaV8 Learn more on APIscene, the global media made by the community for the community: https://www.apiscene.io Explore the API ecosystem with the API Landscape: https://apilandscape.apiscene.io/

Advanced Web Design And Development BIT 3207

Lori Head

Api design best practice

Red Hat

The API Lifecycle Series: Exploring Design-First and Code-First Approaches to...

SmartBear

WebSockets wiith Scala and Play! Framework

Fabio Tiriticco

RESTful web APIs (build, document, manage)

Cisco DevNet

apidays LIVE Paris 2021 - Lessons from the API Stewardship Journey in Azure b...

apidays

Rest WebAPI with OData

Mahek Merchant

Tutorial Workgroup - Working with Forks

PascalDesmarets1

With the fork & pull strategy, contributors create their own (remote) copy of the original repository and push changes to that copy, which is referred to as a fork. Once a contribution is ready, it can be submitted through a pull request: the contributor basically requests the maintainer(s) of the original repository to pull into that repository the work that has been prepared in a fork. Note that nothing prevents multiple contributors from working together in the same fork prior to submitting their changes to the original repository. The main advantage of the fork & pull strategy is that the contributors do not need to be explicitly granted push access rights to the original repository. That's why that strategy is typically used for large-scale open source projects where most contributors are not known by the maintainers of the repository. Another advantage of the fork & pull strategy is that it prevents the original repository from being polluted with branches that are created and then abandoned but never deleted by their author.

Tutorial Advanced How-To - Oracle 23c Duality views

PascalDesmarets1

Mais conteúdo relacionado

Semelhante a Hackolade Tutorial - part 12 - Create a REST API model

IBM Integration Bus and REST APIs - Sanjay Nagchowdhury

Karen Broughton-Mabbitt

Introduction to SignalR

University of Hawai‘i at Mānoa

Mvc 4.0

Ram Ayyalaraju

James Higginbotham - API Design

John Zozzaro

(ATS6-PLAT04) Query service

BIOVIA

Logic apps and PowerApps - Integrate across your APIs

Sriram Hariharan

Lessons learned on the Azure API Stewardship Journey.pptx

apidays

Tutorial Workgroup - Model versioning and collaboration

PascalDesmarets1

Code for Startup MVP (Ruby on Rails) Session 1

Henry S

Scribe online 03 scribe online cdk and api overview

Scribe Software Corp.

CC Technology Summit 3 Update

Nathan Yergler

Brushing skills on SignalR for ASP.NET developers

ONE BCG

Apidays Paris 2023 - Managing OpenAPI Documents at Scale, Stéve Sfartz, Cisco

apidays

Advanced Web Design And Development BIT 3207

Lori Head

Api design best practice

Red Hat

The API Lifecycle Series: Exploring Design-First and Code-First Approaches to...

SmartBear

WebSockets wiith Scala and Play! Framework

Fabio Tiriticco

RESTful web APIs (build, document, manage)

Cisco DevNet

apidays LIVE Paris 2021 - Lessons from the API Stewardship Journey in Azure b...

apidays

Rest WebAPI with OData

Mahek Merchant

Semelhante a Hackolade Tutorial - part 12 - Create a REST API model (20)

IBM Integration Bus and REST APIs - Sanjay Nagchowdhury

Introduction to SignalR

Mvc 4.0

James Higginbotham - API Design

(ATS6-PLAT04) Query service

Logic apps and PowerApps - Integrate across your APIs

Lessons learned on the Azure API Stewardship Journey.pptx

Tutorial Workgroup - Model versioning and collaboration

Code for Startup MVP (Ruby on Rails) Session 1

Scribe online 03 scribe online cdk and api overview

CC Technology Summit 3 Update

Brushing skills on SignalR for ASP.NET developers

Apidays Paris 2023 - Managing OpenAPI Documents at Scale, Stéve Sfartz, Cisco

Advanced Web Design And Development BIT 3207

Api design best practice

The API Lifecycle Series: Exploring Design-First and Code-First Approaches to...

WebSockets wiith Scala and Play! Framework

RESTful web APIs (build, document, manage)

apidays LIVE Paris 2021 - Lessons from the API Stewardship Journey in Azure b...

Rest WebAPI with OData

Mais de PascalDesmarets1

Tutorial Workgroup - Working with Forks

PascalDesmarets1

Tutorial Advanced How-To - Oracle 23c Duality views

PascalDesmarets1

Tutorial Expert How-To - Docker-based automation

PascalDesmarets1

Tutorial Getting Started part 4 - Domain-Driven Data Modeling

PascalDesmarets1

Tackling complexity at the heart of data. With Domain-Driven Data Modeling (DDDM) the main principles are: - focus on your core ("domain and sub-domains") - break down complex problems into smaller ones ("bounded context") - use data modeling as a communication tool ("ubiquitous language") - keep together what belongs together ("aggregates") - reach a shared understanding between business and tech ("collaboration of domain experts and developers") - iterate and evolve ("continuous refinement")

Tutorial Getting Started part 3 - Metadata-as-Code

PascalDesmarets1

Co-locate data models and their schema artifacts with application code, so they can follow the lifecycle of application changes. Provides a single source-of-truth for business and technical stakeholders as the data model in the Git repo is the source of the technical schemas used by applications, databases, and APIs at the same time as it is the source for the business-facing data dictionaries. This architecture contributes to the shared understanding of the context and meaning of data by all the stakeholders.

Tutorial Getting Started part 2 - Polyglot Data Modeling

PascalDesmarets1

Tutorial Expert How-To - Create a model for Avro schemas

PascalDesmarets1

Apache Avro is a language-neutral data serialization system, developed by Doug Cutting, the father of Hadoop. Avro is a preferred tool to serialize data in Hadoop. It is also the best choice as file format for data streaming with Kafka. Avro serializes the data which has a built-in schema. Avro serializes the data into a compact binary format, which can be deserialized by any application. Avro schemas defined in JSON, facilitate implementation in the languages that already have JSON libraries. Avro creates a self-describing file named Avro Data File, in which it stores data along with its schema in the metadata section.

Tutorial Getting Started part 1 - Overview

PascalDesmarets1

Tutorial Expert How-To - Verify Data Model

PascalDesmarets1

Tutorial Expert How-To - Naming Conventions

PascalDesmarets1

Hackolade Studio includes the ability to maintain both a ‘business name’ and a ‘technical name’ for objects (containers, entities, and attributes.) To facilitate the maintenance of these 2 names, it is possible to keep them synchronized and transformed based on a set of user-driven parameters, and optionally based on a conversion file maintained outside of the application. Name conversion can go both directions: Business-to-Technical, or Technical-to-Business. Furthermore, when performing reverse-engineering, it is assumed that the database instance contains technical names, to be transformed in business names.

Tutorial Expert How-To - Export-Import with Excel template

PascalDesmarets1

Exchanging data with Excel provides the ability to export a data model, or parts of it, to Microsoft Excel so properties could be easily edited in a tabular format, to be re-imported back into the application. It facilitates productive bulk actions for the maintenance of properties. It also allows creation of a new model - or additions to an existing model - by team members that might not have access to the application.

Tutorial Expert How-To - Compare and Merge

PascalDesmarets1

An organization may create several different versions through the lifecycle of a model. That may be because of the natural evolution of the application in a design-first process, or just to keep up with changes being applied to the database instance. In any case, it is often required to compare different versions of a model to understand the differences, and optionally to merge these differences and create a new reference model.

Tutorial Expert How-To - Custom properties

PascalDesmarets1

Tutorial Expert How-To - Add reusable Definitions

PascalDesmarets1

Hackolade Tutorial - part 13 - Leverage a Polyglot data model

PascalDesmarets1

Hackolade Tutorial - part 8 - Import or reverse-engineer.pdf

PascalDesmarets1

Hackolade Tutorial - part 6 - Add choice, conditional, pattern fields.pdf

PascalDesmarets1

Hackolade Tutorial - part 4 - Create your first data model

PascalDesmarets1

Hackolade Tutorial - part 3 - Query-driven data modeling based on access patt...

PascalDesmarets1

Data modeling for relational databases is performed according to the rules of normalization, so larger tables are divided into smaller ones linked together with relationships. The purpose is to eliminate redundant or duplicate data. But NoSQL databases are completely different. They require a mindshift in schema design in order to leverage their capabilities, as well as a data modeling tool built specially for this new breed of state-of-the art technology.

Hackolade Tutorial - part 2 - Overview of JSON and JSON schema

PascalDesmarets1

Mais de PascalDesmarets1 (20)

Tutorial Workgroup - Working with Forks

Tutorial Advanced How-To - Oracle 23c Duality views

Tutorial Expert How-To - Docker-based automation

Tutorial Getting Started part 4 - Domain-Driven Data Modeling

Tutorial Getting Started part 3 - Metadata-as-Code

Tutorial Getting Started part 2 - Polyglot Data Modeling

Tutorial Expert How-To - Create a model for Avro schemas

Tutorial Getting Started part 1 - Overview

Tutorial Expert How-To - Verify Data Model

Tutorial Expert How-To - Naming Conventions

Tutorial Expert How-To - Export-Import with Excel template

Tutorial Expert How-To - Compare and Merge

Tutorial Expert How-To - Custom properties

Tutorial Expert How-To - Add reusable Definitions

Hackolade Tutorial - part 13 - Leverage a Polyglot data model

Hackolade Tutorial - part 8 - Import or reverse-engineer.pdf

Hackolade Tutorial - part 6 - Add choice, conditional, pattern fields.pdf

Hackolade Tutorial - part 4 - Create your first data model

Hackolade Tutorial - part 3 - Query-driven data modeling based on access patt...

Hackolade Tutorial - part 2 - Overview of JSON and JSON schema

Último

Uni Systems Copilot event_05062024_C.Vlachos.pdf

Uni Systems S.M.S.A.

FIDO Alliance Osaka Seminar: Overview.pdf

FIDO Alliance

Communications Mining Series - Zero to Hero - Session 1

DianaGray10

This session provides introduction to UiPath Communication Mining, importance and platform overview. You will acquire a good understand of the phases in Communication Mining as we go over the platform with you. Topics covered: • Communication Mining Overview • Why is it important? • How can it help today’s business and the benefits • Phases in Communication Mining • Demo on Platform overview • Q/A

Free Complete Python - A step towards Data Science

RinaMondal9

LF Energy Webinar: Electrical Grid Modelling and Simulation Through PowSyBl -...

DanBrown980551

Do you want to learn how to model and simulate an electrical network from scratch in under an hour? Then welcome to this PowSyBl workshop, hosted by Rte, the French Transmission System Operator (TSO)! During the webinar, you will discover the PowSyBl ecosystem as well as handle and study an electrical network through an interactive Python notebook. PowSyBl is an open source project hosted by LF Energy, which offers a comprehensive set of features for electrical grid modelling and simulation. Among other advanced features, PowSyBl provides: - A fully editable and extendable library for grid component modelling; - Visualization tools to display your network; - Grid simulation tools, such as power flows, security analyses (with or without remedial actions) and sensitivity analyses; The framework is mostly written in Java, with a Python binding so that Python developers can access PowSyBl functionalities as well. What you will learn during the webinar: - For beginners: discover PowSyBl's functionalities through a quick general presentation and the notebook, without needing any expert coding skills; - For advanced developers: master the skills to efficiently apply PowSyBl functionalities to your real-world scenarios.

Video Streaming: Then, Now, and in the Future

Alpen-Adria-Universität

In his public lecture, Christian Timmerer provides insights into the fascinating history of video streaming, starting from its humble beginnings before YouTube to the groundbreaking technologies that now dominate platforms like Netflix and ORF ON. Timmerer also presents provocative contributions of his own that have significantly influenced the industry. He concludes by looking at future challenges and invites the audience to join in a discussion.

GraphSummit Singapore | Graphing Success: Revolutionising Organisational Stru...

Neo4j

Sudheer Mechineni, Head of Application Frameworks, Standard Chartered Bank Discover how Standard Chartered Bank harnessed the power of Neo4j to transform complex data access challenges into a dynamic, scalable graph database solution. This keynote will cover their journey from initial adoption to deploying a fully automated, enterprise-grade causal cluster, highlighting key strategies for modelling organisational changes and ensuring robust disaster recovery. Learn how these innovations have not only enhanced Standard Chartered Bank’s data infrastructure but also positioned them as pioneers in the banking sector’s adoption of graph technology.

Smart TV Buyer Insights Survey 2024 by 91mobiles.pdf

91mobiles

GraphRAG is All You need? LLM & Knowledge Graph

Guy Korland

Guy Korland, CEO and Co-founder of FalkorDB, will review two articles on the integration of language models with knowledge graphs. 1. Unifying Large Language Models and Knowledge Graphs: A Roadmap. https://arxiv.org/abs/2306.08302 2. Microsoft Research's GraphRAG paper and a review paper on various uses of knowledge graphs: https://www.microsoft.com/en-us/research/blog/graphrag-unlocking-llm-discovery-on-narrative-private-data/

Transcript: Selling digital books in 2024: Insights from industry leaders - T...

BookNet Canada

The publishing industry has been selling digital audiobooks and ebooks for over a decade and has found its groove. What’s changed? What has stayed the same? Where do we go from here? Join a group of leading sales peers from across the industry for a conversation about the lessons learned since the popularization of digital books, best practices, digital book supply chain management, and more. Link to video recording: https://bnctechforum.ca/sessions/selling-digital-books-in-2024-insights-from-industry-leaders/ Presented by BookNet Canada on May 28, 2024, with support from the Department of Canadian Heritage.

Monitoring Java Application Security with JDK Tools and JFR Events

Ana-Maria Mihalceanu

Securing your Kubernetes cluster_ a step-by-step guide to success !

KatiaHIMEUR1

Today, after several years of existence, an extremely active community and an ultra-dynamic ecosystem, Kubernetes has established itself as the de facto standard in container orchestration. Thanks to a wide range of managed services, it has never been so easy to set up a ready-to-use Kubernetes cluster. However, this ease of use means that the subject of security in Kubernetes is often left for later, or even neglected. This exposes companies to significant risks. In this talk, I'll show you step-by-step how to secure your Kubernetes cluster for greater peace of mind and reliability.

Elizabeth Buie - Older adults: Are we really designing for our future selves?

Nexer Digital

Introduction to CHERI technology - Cybersecurity

mikeeftimakis1

GridMate - End to end testing is a critical piece to ensure quality and avoid...

ThomasParaiso2

Observability Concepts EVERY Developer Should Know -- DeveloperWeek Europe.pdf

Paige Cruz

Monitoring and observability aren’t traditionally found in software curriculums and many of us cobble this knowledge together from whatever vendor or ecosystem we were first introduced to and whatever is a part of your current company’s observability stack. While the dev and ops silo continues to crumble….many organizations still relegate monitoring & observability as the purview of ops, infra and SRE teams. This is a mistake - achieving a highly observable system requires collaboration up and down the stack. I, a former op, would like to extend an invitation to all application developers to join the observability party will share these foundational concepts to build on:

GraphSummit Singapore | The Art of the Possible with Graph - Q2 2024

Neo4j

FIDO Alliance Osaka Seminar: Passkeys and the Road Ahead.pdf

FIDO Alliance

Encryption in Microsoft 365 - ExpertsLive Netherlands 2024

Albert Hoitingh

Generative AI Deep Dive: Advancing from Proof of Concept to Production

Aggregage

Hackolade Tutorial - part 12 - Create a REST API model

2. 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 Copyright © 2016-2023 Hackolade 2

3. 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 Copyright © 2016-2023 Hackolade 3

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

7. 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 Copyright © 2016-2023 Hackolade 7

11. Create reusable components 4. A couple of responses Copyright © 2016-2023 Hackolade 11 Create a response structure Template gets created Start with 200 - OK The structure now references the component schema:

24. 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 Copyright © 2016-2023 Hackolade 24

25. 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 Copyright © 2016-2023 Hackolade 25

Hackolade Tutorial - part 12 - Create a REST API model

Recomendados

Recomendados

Mais conteúdo relacionado

Semelhante a Hackolade Tutorial - part 12 - Create a REST API model

Semelhante a Hackolade Tutorial - part 12 - Create a REST API model (20)

Mais de PascalDesmarets1

Mais de PascalDesmarets1 (20)

Último

Último (20)

Hackolade Tutorial - part 12 - Create a REST API model