Introduction to

Agenda

  • What is Open API
  • What are competing standards
  • What are the adoption benefits in ComeOn's context
  • How to start
  • Examples, Help and inspirations

About me

My day to day work?

Russian roulette 🔫
☕
🐞
🎁
📅

Task of the day

The result

The fix

Not quite

They said boss is not happy!!!

Dunno, reading faces is't my soft skill

"Did you call the right service?"

– Colleagues

Services?

  • A modern app is devided into multiple logical services.
  • These services expose APIs for interaction with other services or Apps.
  • In context of this talk APIs refer to Rest APIs served over HTTP

More precisely these...

How to use a service?

  • Get the URL of service
  • Call with correct method (GET, POST, PUT etc.)
  • Use correct Content-Type and other request headers.
  • ...and don't forget correct payload
  • Hmm, one last thing, some URLs may contain query parameters. They are very important.

Life was fun again

- A happy app sliding on service mesh circa 2018

... Until it wasn't

- A sad app protesting against too much exploitation circa 2018

Few JIRA's later

Checklist continues

  • If something is wrong services response contains error message.
  • Services might have different error message data structure.
  • If service is unavailable or server throws, you might not get response in expected content type, so handle that as well, Please.

Woes of new feature

Great sportsmanship

- Overwhelming response from a service.

Colleagues are great

  • I've been encouraged to read sourcecode of various services.
  • I've been informed about any changes in API.
  • I've been coached with methods to investigate and debug the issues.
  • Even they sometime handle frontend issues only to realise halfway that it's frontend issue.

Have you got one to cover you?

Not everyone is that lucky...

For you there are other ways to describe APIs

What is Open API?

Programming language-agnostic specification standard to govern how REST APIs are described.

Features

  • Helps you describe REST APIs in texual format (JSON, yaml)
  • Difinition files can be written by hand or auto generated
  • These API definitions can be consumed by Humans and Machines alike
  • Tooling can generate API documentation and mocks
  • In active development and adopted by all the big players in industry

Tooling

Swagger is a set of tooling which helps generating Open API specification.

  • Swagger Codegen Auto generate server stubs and client SDKs for any API
  • Swagger Editor Design, describe, and document your API
  • Swagger UI visualize and interact with the API’s resources without having any of the implementation logic in place.

Premium tooling

Benefits

  • Improve collaboration between service provider and consumer
  • Improve discoverability of services (for humans and machines)
  • Promote predictable service usage
  • Early feedback during development life cycle
  • Help in spoting integration bugs / issues early and easily

How to start

Don't worry about exhaustive list

It's just an Introduction

There will be more.

Questions

The end