Atjaunināt sīkdatņu piekrišanu

Designing APIs with Swagger and OpenAPI [Mīkstie vāki]

4.23/5 (55 ratings by Goodreads)
,
  • Formāts: Paperback / softback, 400 pages, height x width x depth: 232x188x20 mm, weight: 760 g
  • Izdošanas datums: 15-Jun-2022
  • Izdevniecība: Manning Publications
  • ISBN-10: 1617296287
  • ISBN-13: 9781617296284
Citas grāmatas par šo tēmu:
  • Mīkstie vāki
  • Cena: 61,73 €
  • Grāmatu piegādes laiks ir 3-4 nedēļas, ja grāmata ir uz vietas izdevniecības noliktavā. Ja izdevējam nepieciešams publicēt jaunu tirāžu, grāmatas piegāde var aizkavēties.
  • Daudzums:
  • Ielikt grozā
  • Piegādes laiks - 4-6 nedēļas
  • Pievienot vēlmju sarakstam
Designing APIs with Swagger and OpenAPIPalielināt
  • Formāts: Paperback / softback, 400 pages, height x width x depth: 232x188x20 mm, weight: 760 g
  • Izdošanas datums: 15-Jun-2022
  • Izdevniecība: Manning Publications
  • ISBN-10: 1617296287
  • ISBN-13: 9781617296284
Citas grāmatas par šo tēmu:
Permanent link: https://www.kriso.lv/db/9781617296284.html
Keywords:
Follow real-world API projects from concept to production, and learn hands-on how to describe and design APIs using OpenAPI.

In Designing APIs with Swagger and OpenAPI you will learn how to:

    Understand OpenAPI syntax and structure
    Use Swagger and other tooling to create OpenAPI definitions
    Design authentication and authorization
    Turn an OpenAPI description into online documentation
    Automate processes and generating code
    Iterate an API design with user stories
    Build a frontend against a mock server
    Generate backend code with Swagger Codegen
    Versioning an API and dodging breaking changes
    Work with cross-functional teams

Designing APIs with Swagger and OpenAPI is a comprehensive guide to designing and describing your first RESTful API using the most widely adopted standards. Following expert instruction from Swagger core contributor Josh Ponelat and API consultant Lukas Rosenstock, you’ll spend each chapter progressively expanding the kind of APIs you’ll want to build in the real world. You’ll utilize OpenAPI and Swagger to help automate your workflow, and free up your time to work on more exciting features. Learn the syntax and structure of OpenAPI definitions, create and iterate on an API design with common tools, and release your API to the public.

Purchase of the print book includes a free eBook in PDF, Kindle, and ePub formats from Manning Publications.

About the technology
Create web APIs that customers and developers will love! Using Swagger, a collection of tools for defining and documenting REST APIs, you will build safe, controlled access to your software. And because Swagger implements the vendor-neutral OpenAPI specification, you’ll be building to the same standards adopted by Google, Microsoft, and Amazon.

About the book
Designing APIs with Swagger and OpenAPI introduces a design-first approach. Written for developers new to API design, it follows the lifecycle of an API project from concept to production. You’ll explore the dos and don’ts of APIs through progressively complete examples. You’ll get hands-on experience designing APIs for specific business needs, using open source tools to generate documentation, and building developer-friendly components like mocks and client SDKs.

What's inside

    OpenAPI syntax and structure
    Using Swagger to create OpenAPI definitions
    Automating processes and generating code
    Working with cross-functional teams

About the reader
For web developers. No prior knowledge of Swagger or OpenAPI required.

About the author
Josh Ponelat is the Swagger Open Source lead at SmartBear. Lukas Rosenstock is an independent software developer and API consultant.

Table of Contents
PART 1 DESCRIBING APIS
1 Introducing APIs and OpenAPI
2 Getting set up to make API requests
3 Our first taste of OpenAPI definitions
4 Using Swagger Editor to write OpenAPI definitions
5 Describing API responses
6 Creating resources
7 Adding authentication and authorization
8 Preparing and hosting API documentation
PART 2 DESIGN-FIRST
9 Designing a web application
10 Creating an API design using OpenAPI
11 Building a change workflow around API design–first
12 Implementing frontend code and reacting to changes
13 Building a backend with Node.js and Swagger Codegen
14 Integrating and releasing the web application
PART 3 EXTENDING APIS
15 Designing the next API iteration
16 Designing schemas with composition in OpenAPI
17 Scaling collection endpoints with filters and pagination
18 Supporting the unhappy path: Error handling with problem+json
19 Improving input validation with advanced JSON Schema
20 Versioning an API and handling breaking changes
21 The API prerelease checklist

Recenzijas

A great introduction to the design process of APIs by helping youto understand OpenAPI and Swagger. Ben McNamara

The book's instructional design was very well thought out.Instructions are clear and the topics flow quite smoothly. Ted Hagos

I would recommend this book to anyone interested in learningabout API design! Travis Wisnasky

Foreword xix
Preface xx
Acknowledgments xxii
About this book xxiii
About the authors xxvi
About the cover illustration xxvii
Part 1 Describing APIs
1(2)
1 Introducing APIs and OpenAPI
3(1)
1.1 What is an API ecosystem?
3(1)
1.2 Describing things
4(1)
Bridget's task
4(1)
The potential of Bridget's solution
5(1)
1.3 What is OpenAPI?
5(2)
Example OpenAPI definition
6(1)
1.4 Where do OpenAPI definitions fit in?
7(1)
1.5 What is Swagger?
8(1)
1.6 What about REST?
9(1)
1.7 When to use OpenAPI
10(1)
For API consumers
10(1)
For API producers
11(1)
For API designers
11(1)
1.8 This book
11(2)
2 Getting set up to make API requests
13(13)
2.1 The problem
14(1)
FarmStall API overview
14(1)
The first two operations of the FarmStall API
14(1)
2.2 Getting set up with Postman
15(1)
2.3 FarmStall API
16(1)
2.4 Our first request
16(2)
Forming a GET request in Postman
17(1)
Verification
18(1)
2.5 Adding a review to the FarmStall API
18(3)
Forming a POST request in Postman
19(2)
Verification
21(1)
2.6 Practice
21(2)
Cat (and other animal) facts API
21(1)
Random avatar API
22(1)
DuckDuckGo's search engine API
22(1)
Pirate talk API
22(1)
2.7 HTTP for the brave
23(3)
3 Our first taste of OpenAPI definitions
26(9)
3.1 The problem
28(1)
3.2 Introducing the OpenAPI specification
29(1)
3.3 A quick refresher on YAML
29(3)
From JSON to YAML
31(1)
3.4 Describing our first operation
32(1)
3.5 Extending our first operation
33(2)
4 Using Swagger Editor to write OpenAPI definitions
35(13)
4.1 Introducing Swagger Editor
37(1)
The Editor panel
37(1)
The UI Docs panel
37(1)
The toolbar
38(1)
Persistence
38(1)
4.2 Writing the smallest OpenAPI definition in Swagger Editor
38(3)
The smallest valid OpenAPI definition
38(1)
Writing in Swagger Editor
39(1)
A word on validation
40(1)
4.3 Adding GET /reviews to our definition
41(1)
4.4 Interacting with our API
42(6)
Executing GET /reviews
43(1)
Adding servers to our definition
44(1)
Executing GET /reviews (again)
45(3)
5 Describing API responses
48(16)
5.1 HTTP responses
49(1)
5.2 The problem
50(1)
5.3 The mind-blowing world of data schemas
51(1)
5.4 JSON Schema
51(4)
The type field
52(1)
Adding a field to an object
53(1)
The minimum and maximum keywords
53(1)
Number vs. integer
54(1)
5.5 Status codes
55(1)
5.6 Media types (aka MIME)
56(1)
5.7 Describing the GET /reviews response
57(7)
Smallest response in OpenAPI
57(143)
The GET /reviews 200 Response Body
57(1)
Adding the rating field to our response body
58(1)
Describing message, uuid, and userld
59(5)
6 Creating resources
64(18)
6.1 The problem
65(1)
6.2 Describing POST /reviews with a request body
66(5)
Where to find request bodies
69(1)
Describing the schema for POST /reviews requestBody
70(1)
6.3 Executing operations with request bodies
71(4)
Adding examples to make try-it-out look pretty
74(1)
6.4 Describing GET /reviews/{reviewld} with a path parameter
75(3)
Path parameters
76(1)
Describing the reviewldpath parameter
77(1)
6.5 Verifying our reviews are getting created
78(4)
7 Adding authentication and authorization
82(17)
7.1 The problem
84(1)
7.2 Getting set up for authentication
85(6)
Challenge: Describe POST /users
86(1)
Challenge: Describe POST /tokens
86(2)
Solution: Definition changes
88(1)
Verifying we can create users and get a token
89(2)
7.3 Adding the Authorization header
91(5)
How OpenAPI handles authorization
92(1)
Types of authorization (securities) supported in OpenAPI 3.0.x
92(1)
Adding the Authorization header security scheme
93(1)
Adding the security requirements to POST/reviews
94(1)
Using the security feature of try-it-out
94(2)
7.4 Optional security
96(1)
7.5 Other types of security schemas
97(1)
7.6 How to add security schemes in general
97(2)
8 Preparing and hosting API documentation
99(22)
8.1 The problem
100(3)
8.2 Adding metadata to the definition
103(2)
8.3 Writing the description in Markdown
105(6)
Markdown basics
106(2)
Adding a rich text description to the FarmStall API definition
108(3)
8.4 Organizing operations with tags
111(3)
Adding the Reviews tag to GET/reviews
112(1)
Adding descriptions to tags
112(1)
Adding the rest of the tags
113(1)
8.5 Hosting our API documentation using Netlify.com and Swagger UI
114(6)
Preparing Swagger UI with our definition
115(1)
Hosting on Netlify.com
116(4)
8.6 The end of part 1
120(1)
Part 2 Design-first
121(116)
9 Designing a web application
123(19)
9.1 The PetSitter idea
124(1)
9.2 PetSitter project kickoff
124(4)
Additional requirements
124(1)
Team structure
125(1)
API-driven architecture
126(1)
The plan
127(1)
9.3 Domain modeling and APIs
128(3)
Domain modeling for APIs
130(1)
Looking back on FarmStall
130(1)
9.4 A domain model for PetSitter
131(3)
Concepts in the model
131(1)
The User model
132(1)
The Job and Dog models
133(1)
9.5 User stories for PetSitter
134(8)
What are user stories?
134(1)
Collecting user stories
134(2)
Mapping user stories
136(6)
10 Creating an API design using OpenAPI
142(26)
10.1 The problem
143(2)
Converting a domain model to OpenAPI
143(1)
Ensuring reusability
144(1)
10.2 Creating the schemas
145(7)
Starting an OpenAPI file with schemas
145(1)
Referencing common schemas
146(1)
The User schema
146(2)
The Job schema
148(2)
The Dog schema
150(1)
The Job Application schema
151(1)
10.3 The CRUD approach to API operations
152(4)
Defining API requests and responses
154(2)
From user stories to CRUD design
156(1)
10.4 API operations for PetSitter
156(12)
User operations
156(3)
Job operations
159(4)
JobApplication operations
163(5)
11 Building a change workflow around API design-first
168(14)
11.1 The problem
169(2)
11.2 Communicating and reacting to change
171(1)
11.3 GitHub as our workflow engine
172(3)
A single source of truth
173(1)
Suggesting a change
173(1)
Agreeing on a change
173(1)
A way of viewing changes (based on an older version)
174(1)
11.4 Tying the GitHub workflow together
175(2)
Setting up GitHub and the source of truth
175(1)
Steps in our GitHub workflow
176(1)
11.5 A practical look at the workflow
177(5)
Creating and suggesting DELETE /jobs/{id}
177(1)
Reviewing and accepting changes
178(1)
Comparing older branches to the latest
179(1)
What we've done
180(2)
12 Implementing frontend code and reacting to changes
182(16)
12.1 The problem
183(1)
12.2 Setting up Prism
183(2)
Installing Prism
183(1)
Verifying that Prism works
184(1)
12.3 Building a frontend based on a mock server
185(4)
Adding multiple examples into your OpenAPI definition
187(1)
Using examples in Prism
188(1)
12.4 Identifying a missing API operation
189(9)
Due diligence for adding the operation
190(1)
Designing the new operation
190(3)
Choosing which mock data response to get from Prism
193(2)
Formalizing and suggesting the change
195(1)
Extra curl examples
196(2)
13 Building a backend with Node.js and Swagger Codegen
198(23)
13.1 The problem
199(1)
13.2 Introducing Swagger Codegen
199(2)
Client code generation
200(1)
Server code generation
200(1)
Swagger Generator
200(1)
13.3 The backend structure
201(3)
Generating the backend
201(1)
Investigating the structure
201(2)
OpenAPI changes
203(1)
13.4 Updating OpenAPI for the backend
204(5)
Adding operation IDs
204(2)
Tagging API operations
206(2)
Regenerating the backend stubs
208(1)
13.5 Running and testing the backend
209(3)
Testing with Postman
209(1)
Testing input validation
210(1)
Output validation with Prism
211(1)
13.6 Database persistence with Mongoose
212(6)
Another API modification
213(1)
Getting ready to use MongoDB
214(1)
Configuring Mongoose in the project
214(1)
Creating models
214(4)
13.7 Implementing API methods
218(3)
14 Integrating and releasing the web application
221(16)
14.1 The problems
222(3)
Authentication
222(1)
Organizing code
223(1)
Serving both components
224(1)
14.2 Implementing authorization
225(6)
Creating a security scheme
225(1)
Adding a "Login" action
226(3)
Defining operation security
229(2)
14.3 Managing repositories
231(1)
Keeping the existing structure
231(1)
Creating a shared Git repository to implement both components
231(1)
Combining code and API definition in a repository
231(1)
Making the choice and refactoring
232(1)
14.4 Setting up an integrated web server
232(5)
URI, design
232(2)
Server setup
234(3)
Part 3 Extending APIs
237(146)
15 Designing the next API iteration
239(14)
15.1 Reviewing the first development sprint
240(1)
15.2 Planning the next sprint
241(1)
15.3 Preparing for new features
242(6)
Reviewing the domain model
243(2)
Reviewing user stories
245(3)
15.4 Improving the developer experience
248(5)
Consistency
250(1)
Error handling
250(1)
Input validation
250(1)
Versioning vs. evolvability
251(2)
16 Designing schemas with composition in OpenAPI
253(20)
16.1 The problem
254(3)
16.2 Polymorphism and inheritance in domain models
257(2)
16.3 Updating the schemas
259(3)
The Pet schema
261(1)
The Dog schema
261(1)
The Cat schema
262(1)
16.4 Polymorphism and inheritance in OpenAPI
262(6)
Composition inside the Dog and Cat schemas
264(2)
Composition inside the Pet schema
266(2)
16.5 Adding discriminators in OpenAPI
268(5)
17 Scaling collection endpoints with filters and pagination
273(31)
17.1 The problem
274(2)
17.2 Designing filters
276(6)
Projection filters
277(1)
Selection filters
277(3)
Handling nested schemas
280(1)
Query languages
281(1)
Special conventions
281(1)
17.3 Filters for PetSitter
282(8)
Finding filter fields
282(4)
Adding filters to OpenAPI
286(4)
Making a request
290(1)
17.4 Designing pagination
290(4)
Offset-based and page-based pagination
291(2)
Cursor-based pagination
293(1)
17.5 Pagination for PetSitter
294(3)
Adding pagination to OpenAPI
295(2)
Extending our request example
297(1)
17.6 Designing sorting
297(3)
Single-field sorting
298(1)
Multifield sorting
299(1)
Consistency throughout parameter types
299(1)
17.7 Sorting for PetSitter
300(4)
Finding sorting fields
300(1)
Designing the sort parameter
301(1)
Adding sorting to OpenAPI
301(1)
The final request example
302(2)
18 Supporting the unhappy path: Error handling with problem+json
304(20)
18.1 The problem
305(1)
18.2 Error categories
306(3)
Finding unhappy paths
307(2)
Common error patterns
309(1)
18.3 Requirements for error responses
309(3)
18.4 The OAS tools format
312(2)
18.5 The problem+json format
314(2)
18.6 Adding error responses to OpenAPI
316(4)
Creating error schemas
317(1)
Adding errors to operations
318(2)
18.7 Error-handling guidance
320(4)
Frontend development
320(2)
Backend development
322(2)
19 Improving input validation with advanced JSON Schema
324(29)
19.1 The problem
325(1)
19.2 Supported validations
326(6)
Read-only and write-only properties
326(2)
Enforcing number constraints
328(1)
Enforcing string formats
328(2)
Enforcing array constraints
330(1)
Defining enumerations
331(1)
Listing required and optional properties
331(1)
Setting defaults
332(1)
19.3 Updating PetSitter schemas
332(8)
User schema
333(2)
Job schema
335(1)
JobApplication schema
336(1)
Pet, Dog, and Cat schemas
337(2)
Versioning an API and handling breaking changes
339(1)
20.1 The problem
340(1)
20.2 What is a breaking change?
341(1)
20.3 Releasing a breaking change
341(12)
Coordinated breaking changes
342(1)
Multiple API versions
343(3)
Using media types to version operations
346(3)
Adding and deprecating features
349(4)
21 The API prerelease checklist
353(30)
21.1 Pros and cons of a public API
353(1)
21.2 The checklist
354(2)
21.3 Getting the API working
356(4)
Unit testing your API
356(1)
End-to-end testing
357(3)
21.4 Documentation
360(2)
21.5 Getting your API consistent
362(1)
21.6 Validation and error reporting
363(1)
21.7 An API roadmap and exposure index
363(3)
21.8 Getting a change strategy
366(1)
21.9 Improving security
366(2)
21.10 Monitoring your API
368(1)
Setting up metric collection
368(1)
21.11 Releasing the API
369(14)
Appendix Swagger 2.0, OpenAPI 3.0, and OpenAPI 3.1
371(12)
Index 383
Josh Ponelat is a senior architect working with the Swagger/OpenAPI team at SmartBear. He's based out of Plettenberg Bay, South Africa with his two labradors.

Lukas Rosenstock is an independent software developer, technical writer, API consultant, and entrepreneur who has a decade of experience working in and with start-ups.