COMSE6998: Modern Serverless Cloud Applications

Lecture 4: Lecture 4: TLDS, Swagger, Pagination, RESTAngular,

Programmable Web, 2nd Project

Dr. Donald F. Ferguson

[email protected]

© Donald F. Ferguson, 2016. All rights reserved.

Contents
• Introduction
– TAs
– Project Definitions
– Q&A

• Evolution and Motivation: Web apps à SOA/Microservices à Serverless

• Top-Level Design Specification
• New technical topics
– Swagger
– Pagination
– RESTAngular (Overview)
– Programmable Web

• Second Project: Using Web APIs.

2 COMSE6998 – Modern Serverless Cloud Applications © Donald F. Ferguson, 2016. All rights reserved.
Lecture 4: TLDS, Swagger, Pagination, RESTAngular, Programmable Web, 2nd Project
 Introduction

3 COMSE6998 – Modern Serverless Cloud Applications © Donald F. Ferguson, 2016. All rights reserved.
Lecture 4: TLDS, Swagger, Pagination, RESTAngular, Programmable Web, 2nd Project
TAs
• Kushwanth Ram Kesarla Shantharam
– Just assigned.
– Should be attending class today.

• Jingxiao Gu
– Attends class.
– Has announced office hours.
– Active on Piazza.

• One more to be named, but have a good candidate.

4 COMSE6998 – Modern Serverless Cloud Applications © Donald F. Ferguson, 2016. All rights reserved.
Lecture 4: TLDS, Swagger, Pagination, RESTAngular, Programmable Web, 2nd Project
First Project Requirements (from Lecture 2)
• Define DynamoDB Tables
– Customer (lastname, firstname, email, phone number, address_ref)
– Address (UUID, city, street, number, zip code)
• Implement a Lambda function for Customer and Address, e.g. for Customer
– Methods
– GET – key is “email.”
– POST (Create)
– Body is the data, but …
– Cannot create (POST) if there is already a customer with that email.
– PUT (Update)
– Body is a subset of the JSON fields.
– Update only those fields.
– Cannot update an object that does not exist.
– DELETE – key is email.
– For all function, implement validation checks, e.g. no ”new fields,” zipcode is a number with 5 digits, …
• API Gateway
– Define resources /Customers and /Addresses
– POST on /Customers and /Addresses
– GET, PUT and DELETE on /Customers/{email} and /Addresses/{id}
– Navigation works /Customers/{email}/address returns the address.

5 COMSE6998 – Modern Serverless Cloud Applications © Donald F. Ferguson, 2016. All rights reserved.
Lecture 4: TLDS, Swagger, Pagination, RESTAngular, Programmable Web, 2nd Project
Think, and “Carry a Message to Garcia”
(https://en.wikipedia.org/wiki/A_Message_to_Garcia)

• This definition is unusually detailed for a project of this size.

• In the real world,
– Project assignments focus on “what the functions should be.”
– The engineering team needs to define the “how.”
– Technology.
– Modules/functions.
– Components..
– … ...
• I want to help you learn how to define the concrete from the vague.
• Relax. I am not out to get you. HAVE FUN!

Think. Try. You will make mistakes. Correcting mistakes is how we learn.
6 COMSE6998 – Modern Serverless Cloud Applications © Donald F. Ferguson, 2016. All rights reserved.
Lecture 4: TLDS, Swagger, Pagination, RESTAngular, Programmable Web, 2nd Project
Q&A

7 COMSE6998 – Modern Serverless Cloud Applications © Donald F. Ferguson, 2016. All rights reserved.
Lecture 4: TLDS, Swagger, Pagination, RESTAngular, Programmable Web, 2nd Project
 Top-Level
Design
Specification

8 COMSE6998 – Modern Serverless Cloud Applications © Donald F. Ferguson, 2016. All rights reserved.
Lecture 4: TLDS, Swagger, Pagination, RESTAngular, Programmable Web, 2nd Project
 Agile Development

Traditional “Waterfall” Methodology

Design seems to be missing?

9 COMSE6998 – Modern Serverless Cloud Applications © Donald F. Ferguson, 2016. All rights reserved.
Lecture 4: TLDS, Swagger, Pagination, RESTAngular, Programmable Web, 2nd Project
Observations
Weinberg's Second Law: “If builders built buildings the way programmers wrote programs, then the first
woodpecker that came along would destroy civilization.”

Sr. Celestina: “If you cannot write it down, you do not understand it.”

“it is a custom
More honor'd in the breach than the observance”
Hamlet Act 1, scene 4, 7–16

Agile Manifesto (http://agilemanifesto.org/):

• Individuals and interactions over processes and tools
• Working software over comprehensive documentation
• Customer collaboration over contract negotiation
• Responding to change over following a plan

10 COMSE6998 – Modern Serverless Cloud Applications © Donald F. Ferguson, 2016. All rights reserved.
Lecture 4: TLDS, Swagger, Pagination, RESTAngular, Programmable Web, 2nd Project
4+1 architectural view model
http://en.wikipedia.org/wiki/4%2B1_architectural_view_model

11 COMSE6998 – Modern Serverless Cloud Applications © Donald F. Ferguson, 2016. All rights reserved.
Lecture 4: TLDS, Swagger, Pagination, RESTAngular, Programmable Web, 2nd Project
The Architecture Views
http://en.wikipedia.org/wiki/4%2B1_architectural_view_model
• Logical view : The logical view is concerned with the functionality that the system provides to end-users. UML Diagrams used to represent the
logical view include Class diagram, Communication diagram, Sequence diagram.[2]
• Development view : The development view illustrates a system from a programmer's perspective and is concerned with software management.
This view is also known as the implementation view. It uses the UML Component diagram to describe system components. UML Diagrams
used to represent the development view include the Package diagram.[2]
• Process view : The process view deals with the dynamic aspects of the system, explains the system processes and how they communicate, and
focuses on the runtime behavior of the system. The process view addresses concurrency, distribution, integrators, performance, and scalability,
etc. UML Diagrams to represent process view include the Activity diagram.[2]
• Physical view : The physical view depicts the system from a system engineer's point of view. It is concerned with the topology of software
components on the physical layer, as well as the physical connections between these components. This view is also known as the deployment
view. UML Diagrams used to represent physical view include the Deployment diagram.[2]
• Scenarios : The description of an architecture is illustrated using a small set of use cases, or scenarios which become a fifth view. The scenarios
describe sequences of interactions between objects, and between processes. They are used to identify architectural elements and to illustrate and
validate the architecture design. They also serve as a starting point for tests of an architecture prototype. This view is also known as use case
view

12 COMSE6998 – Modern Serverless Cloud Applications © Donald F. Ferguson, 2016. All rights reserved.
Lecture 4: TLDS, Swagger, Pagination, RESTAngular, Programmable Web, 2nd Project
Some Diagrams
http://www.agilemodeling.com/essays/umlDiagrams.htm

13 COMSE6998 – Modern Serverless Cloud Applications © Donald F. Ferguson, 2016. All rights reserved.
Lecture 4: TLDS, Swagger, Pagination, RESTAngular, Programmable Web, 2nd Project
Some Diagrams Communication Diagram

Class Diagram Sequence Diagram

Component Diagram
Component Diagram
Activity Diagram

14 COMSE6998 – Modern Serverless Cloud Applications © Donald F. Ferguson, 2016. All rights reserved.
Lecture 4: TLDS, Swagger, Pagination, RESTAngular, Programmable Web, 2nd Project
Application to 1st Project Communication Diagram

Class Diagram Sequence Diagram

Component Diagram
Component Diagram
Activity Diagram

15 COMSE6998 – Modern Serverless Cloud Applications © Donald F. Ferguson, 2016. All rights reserved.
Lecture 4: TLDS, Swagger, Pagination, RESTAngular, Programmable Web, 2nd Project
User Stories
• User stories are short, simple descriptions of a feature told from the perspective of the
person who desires the new capability, usually a user or customer of the system. They
typically follow a simple template: (https://www.mountaingoatsoftware.com/agile/user-
stories)
– As a <type of user>, I want <some goal> so that <some reason>.
• Example user stories (http://www.agilemodeling.com/artifacts/userStory.htm)
– Students can purchase monthly parking passes online.
– Parking passes can be paid via credit cards.
– Parking passes can be paid via PayPal.
– Professors can input student marks.
– Students can obtain their current seminar schedule.
– Students can order official transcripts.
– Students can only enroll in seminars for which they have prerequisites.
– Transcripts will be available online via a standard browser

16 COMSE6998 – Modern Serverless Cloud Applications © Donald F. Ferguson, 2016. All rights reserved.
Lecture 4: TLDS, Swagger, Pagination, RESTAngular, Programmable Web, 2nd Project
Agile Development and User Stories

17 COMSE6998 – Modern Serverless Cloud Applications © Donald F. Ferguson, 2016. All rights reserved.
Lecture 4: TLDS, Swagger, Pagination, RESTAngular, Programmable Web, 2nd Project
Documenting API Example
(We will use Swagger and Swagger Editor)
URI https://mysite.com:3911/api/members/{id}

HTTP verb PUT

Parameters id : Card number of the member.

name : Name of the member.
Body email : Email adress of the member.
langage : Langage used by member (Fr_CA ou En_US)
{
"name":"Mario Cardinal",
Sample body "email":“[email protected]",
"language":"fr_CA"
}

Success Status Code: 204 No Content

Response
Status Code: 400 Bad Request, Body: {"Error Code":"..."}
Status Code: 401 Unauthenticated, see WWW-Authenticate value in header
Status Code: 403 Forbidden
Error Response Status Code: 404 Not Found
Status Code: 429 Too Many Requests, see Retry-After value in header
Status Code: 500 Internal Server Error
Status Code: 503 Service Unavailable
10: Inactive member
Error Code 20: Denied access member
110: Database issues, Retry later

18 COMSE6998 – Modern Serverless Cloud Applications © Donald F. Ferguson, 2016. All rights reserved.
Lecture 4: TLDS, Swagger, Pagination, RESTAngular, Programmable Web, 2nd Project
Top-Level Design Specification
• Comments
– I have presented a very systematic version of TLDS content.
– All development projects should do some flavor of this approach, ideally simple and living/dynamic.
– Just want to give you a feel for the types of things you can include in your TLDS, but you only need a
really simple version.
– Use common sense.
• For your TLDS
– You do not need to use UML, but should use some of the concepts.
– Some useful diagrams
– Component diagram.
– Class diagram documenting the logical datamodels/ resource models for components.
– Some sequence diagrams showing end-to-end flows and Lambda functions in flows.
• Define and document
– A couple of user stories.
– Your APIs.

19 COMSE6998 – Modern Serverless Cloud Applications © Donald F. Ferguson, 2016. All rights reserved.
Lecture 4: TLDS, Swagger, Pagination, RESTAngular, Programmable Web, 2nd Project
 New
Topics

20 COMSE6998 – Modern Serverless Cloud Applications © Donald F. Ferguson, 2016. All rights reserved.
Lecture 4: TLDS, Swagger, Pagination, RESTAngular, Programmable Web, 2nd Project
 Swagger

21 COMSE6998 – Modern Serverless Cloud Applications © Donald F. Ferguson, 2016. All rights reserved.
Lecture 4: TLDS, Swagger, Pagination, RESTAngular, Programmable Web, 2nd Project
Swagger

22 COMSE6998 – Modern Serverless Cloud Applications © Donald F. Ferguson, 2016. All rights reserved.
Lecture 4: TLDS, Swagger, Pagination, RESTAngular, Programmable Web, 2nd Project
Swagger Editor: http://editor.swagger.io/#/

23 COMSE6998 – Modern Serverless Cloud Applications © Donald F. Ferguson, 2016. All rights reserved.
Lecture 4: TLDS, Swagger, Pagination, RESTAngular, Programmable Web, 2nd Project
 Models

24 COMSE6998 – Modern Serverless Cloud Applications © Donald F. Ferguson, 2016. All rights reserved.
Lecture 4: TLDS, Swagger, Pagination, RESTAngular, Programmable Web, 2nd Project
 Operations

25 COMSE6998 – Modern Serverless Cloud Applications © Donald F. Ferguson, 2016. All rights reserved.
Lecture 4: TLDS, Swagger, Pagination, RESTAngular, Programmable Web, 2nd Project
 Method Execution

26 COMSE6998 – Modern Serverless Cloud Applications © Donald F. Ferguson, 2016. All rights reserved.
Lecture 4: TLDS, Swagger, Pagination, RESTAngular, Programmable Web, 2nd Project
http://www.slideshare.net/VictorTrakhtenberg/swagger2
Swagger is…
Technology Methodology
A framework A specification
for for
• producing • describing
• consuming • documenting
• visualizing
RESTful APIs RESTful APIs
Getting Started

http://swagger.io/getting-started/

28 COMSE6998 – Modern Serverless Cloud Applications © Donald F. Ferguson, 2016. All rights reserved.
Lecture 4: TLDS, Swagger, Pagination, RESTAngular, Programmable Web, 2nd Project
Introduction to Swagger

Tony Tam
@fehguy
 Why Swagger?

• Integration with REST APIs is troublesome and

inconsistent
• Different vendors have different REST semantics
• Client libraries vary wildly by vendor, language
• Documentation for developers is an afterthought
• Input parameters, allowable values, models, responses are found via
trial & error
• Internally a PITA
• YOUR API is too hard to develop against!
 How Does it Work?
• Your server produces a Resource List
• All available APIs
http://petstore.swagger.wordnik.com/api/resources.json

“It’s like a
sitemap for
your API!”
 How Does it Work?

• Each API declares itself

• Available operations
• Parameters
• Type (path, query, body)
• Allowable values/data types
• Input/output models
• Error responses with descriptions
 Client Library Generation

• Code generation based on Resource Spec

• Template-based Framework
• Consume REST Methods, Models, Parameters
• Produce client libraries
• “Know before you go HTTP”
• Required values, fields are known by the client
• Only expose what’s allowed!
• Swagger filtering removes methods/models you don’t have access to
 Client Library Generation

• Code generation based on Resource Spec

• Template-based Framework
• Consume REST Methods, Models, Parameters
• Produce client libraries
• “Know before you go HTTP”
• Also generation
Required values, for by the client
fields are known
• • Servers, although limited for Lambda.
Only expose
• APIwhat’s allowed!
Gateway.
• • … ... removes methods/models you don’t have access to
Swagger filtering
 Test Framework
• JSON-driven tests for your Client + API
Test Suites Expected data
 Easy to add
• For Java/Scala via JAX-RS…
• Add swagger-core.jar
• Annotate your models per your @Provider class

• Annotate your resources

 Easy to add
• For node.js via express
• Require swagger.js
• Declare your swagger specs, models
• Could use AST/DSL to do automatically
• Add your operations, configure and start
 Easy DIY

• The Swagger spec is Language Agnostic!

• ANY swagger-compliant server can…
• Use the Swagger client lib generator
• Use the test framework
• Use the sandbox UI
• More server support from Wordnik
• Play, Rails
• .net, others community developed
 Swagger Hub
• Methodology for
– Designing
– Building
– Testing
– Finding/Using
“Services”
• Serverless/AWS is
– Programming Model
– For Implementing methods
with
• Agility
• Flexibility
• Efficiency
• … ...
Let’s Walk Through the Example

http://swagger.io/getting-started/

40 COMSE6998 – Modern Serverless Cloud Applications © Donald F. Ferguson, 2016. All rights reserved.
Lecture 4: TLDS, Swagger, Pagination, RESTAngular, Programmable Web, 2nd Project
 Programmable
Web

41 COMSE6998 – Modern Serverless Cloud Applications © Donald F. Ferguson, 2016. All rights reserved.
Lecture 4: TLDS, Swagger, Pagination, RESTAngular, Programmable Web, 2nd Project
www.programmableweb.com

42 COMSE6998 – Modern Serverless Cloud Applications © Donald F. Ferguson, 2016. All rights reserved.
Lecture 4: TLDS, Swagger, Pagination, RESTAngular, Programmable Web, 2nd Project
www.programmableweb.com
• Programmable Web is an example of the concept.
• Documents about 15,000 APIs.
• Sample code, ratings, how-to, …
• The Web is evolving from
• Mostly HTML/pages and human interactions to
• A web of APIs surfacing an enterprise’s capabilities.
• To form an “API Economy.”
(http://www.forbes.com/sites/ciocentral/2012/08/29/welcome-to-
the-api-economy/#747417756d39)
• Application development is evolving from
• Building applications on platforms to
• Composite applications that assemble APIs
• Dynamically developed and evolved using serverless.
43 COMSE6998 – Modern Serverless Cloud Applications © Donald F. Ferguson, 2016. All rights reserved.
Lecture 4: TLDS, Swagger, Pagination, RESTAngular, Programmable Web, 2nd Project
 2nd Project

44 COMSE6998 – Modern Serverless Cloud Applications © Donald F. Ferguson, 2016. All rights reserved.
Lecture 4: TLDS, Swagger, Pagination, RESTAngular, Programmable Web, 2nd Project
Customer and Address Customer

Address

Create a Customer
• I can enter the address information and customer info on one “form” and make two calls.
• How do I know if
– The address does/does not already exist?
– Do I completely match the text? What if one used “S. Salem” and one used “South Salem?”
– If the address already exists, how do I give the user the option of choosing without showing all of
the address in a zipcode?
– … ...
45 COMSE6998 – Modern Serverless Cloud Applications © Donald F. Ferguson, 2016. All rights reserved.
Lecture 4: TLDS, Swagger, Pagination, RESTAngular, Programmable Web, 2nd Project
Reuse an API
Why write a service
And incrementally
Build data if
Someone has
Already done it?

For example
https://smartystreets.com/demo/api

46 COMSE6998 – Modern Serverless Cloud Applications © Donald F. Ferguson, 2016. All rights reserved.
Lecture 4: TLDS, Swagger, Pagination, RESTAngular, Programmable Web, 2nd Project
Example REST Call and Response

Some observations:
1. We will start to understand
API security models.
2. Guesses corrections to
incorrect data, e.g.
misspelling “Pensilvania.”
and missing zipcode.
3. Delivery_point_barcode
provides unique ID, and
duplicate detection.

47 COMSE6998 – Modern Serverless Cloud Applications © Donald F. Ferguson, 2016. All rights reserved.
Lecture 4: TLDS, Swagger, Pagination, RESTAngular, Programmable Web, 2nd Project
Auto-Complete Demo

https://smartystreets.com/demo

48 COMSE6998 – Modern Serverless Cloud Applications © Donald F. Ferguson, 2016. All rights reserved.
Lecture 4: TLDS, Swagger, Pagination, RESTAngular, Programmable Web, 2nd Project
Next Steps in Project
Customer

Address
Verification
• Verification/Correction
• Auto-completion
• etc. Why?

49 COMSE6998 – Modern Serverless Cloud Applications © Donald F. Ferguson, 2016. All rights reserved.
Lecture 4: TLDS, Swagger, Pagination, RESTAngular, Programmable Web, 2nd Project
Assignment 2
• Expand on Assignment #1.
• Expand API functionality
– Fully implement success and error codes.
– Href for address link and self.
– Full Swagger definition, including models.
• Build a simple, ideally AngularJS UI
– CRUD customer information forms.
– Forms to add and change the address associated with a customer,
including auto-complete. (www.smartystreets.com free tier).
• Modify Dynamo DB and Lambda function(s)
– Replace address UUID with Delivery_Point_Barcode.
– An address appears once (is unique) in the DynamoDB table.
– Call www.smartystreets.com to verify on PUT/POST, and throw error/HTTP error if wrong.

50 COMSE6998 – Modern Serverless Cloud Applications © Donald F. Ferguson, 2016. All rights reserved.
Lecture 4: TLDS, Swagger, Pagination, RESTAngular, Programmable Web, 2nd Project