O'Reilly logo
live online training icon Live Online training

API Driven Architecture with Swagger and API Blueprint

Good API Documentation & Design with Open API & API Blueprint

Phil Wilkins

APIs have become a key factor in the development and integration of software, although just generating a swagger file doesn’t amount to a good API. In this course, we will explore the design paradigm of API First, and how it helps to produce well-designed APIs.

We will cover the Open API notation (better known as Swagger) and an alternative open standard API Blueprint. We’ll discuss these notations and the best practices developed by organizations like Google. We’ll also examine a number of different possible tools for working with these notations, in addition to the free-to-use service Apiary, which is featured in the book Implementing Oracle API Platform Cloud Service.

As we review examples of good API design, we’ll also discuss elements of bad API Design, and some alternative strategies to the common REST-based API models. This course will provide a great foundation for API Development, teaching you different approaches to create and document a great API, and how to use several open documentation standards.

What you'll learn-and how you can apply it

  • Open API standard, often referred to as Swagger
  • API Blueprint notation and how it compares to the better-known Swagger
  • How an API First model can enable successful API Design
  • What makes good API documentation
  • Insight into alternate technical options to REST APIs.
  • Introduction to a number of tools and extensions that allow the authoring of API specifications.

This training course is for you because...

You are a developer who wants to better understand the notations for describing APIs, how to design APIs more effectively and provide good documentation without needing to produce hundreds of pages of text.


Comprehension of the following areas will be needed: - The goal of APIs - JSON Notation - YAML Notation - HTTP

This is a Show & Tell session. If you want to follow along then the following will help… - Apiary account - GitHub account - Microsoft code

About your instructor

  • Phil Wilkins has spent over 25 years in the software industry with a breadth of experience in different types of businesses and environments from multinationals to software startups and consumer organizations including a global optical and auditory healthcare provider. He started out as a developer on real-time mission critical solutions and has worked his way up through technical and development leadership roles primarily in Java based environments.

    Phil now works for Capgemini specialising in cloud integration and API technologies as part of a multi award winning PaaS team in the UK. Phil’s role is both client facing with well know national and international brands, as well as supporting the wider practise with technical expertise and leading the innovation initiatives.

    Outside of his work commitments, he has contributed his technical capabilities to supporting others in a wide range of activities from the development of local community websites, to providing input and support to the development of technical books (Packt Publishing, Thomas Erl (Prentice-Hall) etc) including co-authoring the books Implementing Oracle Cloud Integration and Implementing API Platform. He has also had a number of articles published in technical journals in his own right as well as being an active blogger. When not writing Phil is a co-organizer of the London Oracle Developer Meetup and driving force behind the Drones with APIs project.

    Phil is TOGAF certified and recognised by Oracle as part of their Ace community.


The timeframes are only estimates and may vary according to how the class is progressing

Section 1: API First - 15 min

  • Walk through the API first process
  • Why should we entertain API first
  • When to do API first and when I can can’t talk to my consumers

Section 2: Quick introduction to notations available - 10 min

  • API Blueprint
  • Open API / Swagger
  • RAML

Section 3: Tooling to facilitate collaborative API development - 20 min

  • Apiary
  • Apiary quality rules
  • Microsoft Code plugins
  • Swagger tools

Section 4: What makes a good API - 45 min

  • Proper use of HTTP
  • Proper REST
  • What it means to be HATEOAS
  • REST is not SOAP in JSON
  • Good API is more than just a payload definition
  • Sample
  • Mock APIs to work with
  • Providing an SDK (Apimatic) (Show & Tell) TBC
  • Sometimes REST isn’t the best answer – GraphQL etc.
  • Use examples to help illustrate points

Section 5: Open API aka Swagger 10 - min

  • Walking through the notation capabilities
  • Swagger beyond the basics, inclusions etc
  • Use tools to illustrate Notation (Show & Tell)

Section 6: API Blueprint - 10 min

  • Difference to open API
  • From sample to structured definition
  • Beyond the basics, inclusions

Section 7: Summary & bringing it all together - 10 min

  • API 1st
  • What should I ask myself – questions to check myself to be sure api is going well
  • Bad smells

Q&A - 10 mins