Swagger and REST API

history

created in 2011

Tony Tam

Technical Co-founder of Wordnik

objective

wordnik's products

create

automation of API documentation

Client SDK generation

Software Framework

large ecosystem of tools

set of tools

helps developers

Restful Webservice

consume

document

design

build

swagger toolset

test case generation

code generation

automated documentation

OpenAPI Specification (OAS)

API description for REST APIs

describes entire API

defines standard API

language-agnostic interface

helps discover and understand the capabilities of service

formats

YAML

JSON

Objectives

create

details

RESTful contract for your API

Problems

Undermines REST API

reducing REST to a form of RPC contract

less reliable version of WSSDL & SOAP

doesn't describe REST adequately

doesn't describe hypermedia support

key aspect of REST

allows servers to control their own namespace

servers should not be bound by fixed URLs

client should only know the root URL of an API

Focuses on functions of an API

Risks

clients do not always leverage hypermedia

REST should be tolerant to a change of the server