Skip to content

Commit

Permalink
Shuffled things around a bit
Browse files Browse the repository at this point in the history
  • Loading branch information
Phil Sturgeon committed Apr 5, 2019
1 parent 05f612c commit 5cda073
Show file tree
Hide file tree
Showing 54 changed files with 286 additions and 129 deletions.
2 changes: 2 additions & 0 deletions Gemfile
Original file line number Diff line number Diff line change
Expand Up @@ -7,3 +7,5 @@ gem 'asciidoctor-pdf', '~> 1.5.pre'
gem 'asciidoctor-epub3', '~> 1.5.pre'
gem 'asciidoctor-diagram' # https://github.com/asciidoctor/asciidoctor-diagram
gem 'coderay' # markdown
gem "kindlegen", "~> 3.0"
gem "nokogiri", "~> 1.10"
26 changes: 17 additions & 9 deletions Gemfile.lock
Original file line number Diff line number Diff line change
Expand Up @@ -5,12 +5,13 @@ GEM
addressable (2.6.0)
public_suffix (>= 2.0.2, < 4.0)
afm (0.2.2)
asciidoctor (1.5.8)
asciidoctor (2.0.5)
asciidoctor-diagram (1.5.16)
asciidoctor (>= 1.5.0, < 3.x)
asciidoctor-epub3 (1.5.0.alpha.8)
asciidoctor (~> 1.5.0)
gepub (~> 0.6.9.2)
asciidoctor-epub3 (1.5.0.alpha.9)
asciidoctor (>= 1.5.0, < 3.0.0)
concurrent-ruby (~> 1.1.5)
gepub (~> 1.0.2)
thread_safe (~> 0.3.6)
asciidoctor-pdf (1.5.0.alpha.16)
asciidoctor (>= 1.5.0)
Expand All @@ -23,15 +24,19 @@ GEM
thread_safe (~> 0.3.6)
treetop (= 1.5.3)
coderay (1.1.2)
concurrent-ruby (1.1.5)
css_parser (1.7.0)
addressable
gepub (0.6.9.2)
nokogiri (~> 1.6.1)
gepub (1.0.2)
nokogiri (>= 1.8.2, < 1.11)
rubyzip (>= 1.1.1)
hashery (2.1.2)
mini_portile2 (2.1.0)
nokogiri (1.6.8.1)
mini_portile2 (~> 2.1.0)
kindlegen (3.0.3)
rake
rubyzip
mini_portile2 (2.4.0)
nokogiri (1.10.2)
mini_portile2 (~> 2.4.0)
pdf-core (0.7.0)
pdf-reader (2.2.0)
Ascii85 (~> 1.0.0)
Expand All @@ -54,6 +59,7 @@ GEM
pdf-reader (~> 2.0)
prawn (~> 2.2)
public_suffix (3.0.3)
rake (12.3.2)
ruby-rc4 (0.1.5)
rubyzip (1.2.2)
safe_yaml (1.0.5)
Expand All @@ -71,6 +77,8 @@ DEPENDENCIES
asciidoctor-epub3 (~> 1.5.pre)
asciidoctor-pdf (~> 1.5.pre)
coderay
kindlegen (~> 3.0)
nokogiri (~> 1.10)

BUNDLED WITH
2.0.1
20 changes: 12 additions & 8 deletions Makefile
Original file line number Diff line number Diff line change
Expand Up @@ -4,18 +4,22 @@ install:
brew bundle
bundle install

build: build-html build-pdf build-epub
build: build-html build-pdf build-epub build-mobi

build-html:
rm -rf generated/html/*
asciidoctor book.adoc -r asciidoctor-diagram -b html5 -D generated/html
mkdir -p generated/html/1-theory && cp -r 1-theory/images generated/html/1-theory/
mkdir -p generated/html/2-planning && cp -r 2-planning/images generated/html/2-planning/
asciidoctor -r asciidoctor-diagram -b html5 -D generated/html src/book.adoc
mkdir -p generated/html/1-theory && cp -r src/1-theory/images generated/html/1-theory/
mkdir -p generated/html/2-planning && cp -r src/2-planning/images generated/html/2-planning/

build-pdf:
asciidoctor-pdf book.adoc -r asciidoctor-diagram -D generated
asciidoctor-pdf -r asciidoctor-diagram -D generated src/book.adoc

build-epub:
export XML_CATALOG_FILES=/usr/local/etc/xml/catalog
a2x book.adoc -r asciidoctor-diagram -v -fepub -dbook --no-xmllint
mkdir generated/epub && mv book.epub generated/epub/
#export XML_CATALOG_FILES=/usr/local/etc/xml/catalog
#a2x src/book.adoc -r asciidoctor-diagram -v -fepub -dbook --no-xmllint
#mkdir generated/epub && mv book.epub generated/epub/
asciidoctor-epub3 -D generated src/book.adoc

build-mobi:
asciidoctor-epub3 -D generated -a ebook-format=kf8 src/book.adoc
117 changes: 60 additions & 57 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,71 +2,74 @@

The API World has changed a lot since 2014, and keeping the original book up-to-date with blog posts and bonus chapters in the ebook is only holding off the inevitable for so long.

Support the development of this book, and [*pre-order on LeanPub!*](https://leanpub.com/build-apis-2/)

## Outline

So far, this feels like how the book is gonna play out:

- [ ] Part One: Theory
- [x] APIs, Services, and Microservices
- [x] Understanding Different Paradigms
- [x] API Contracts
- [ ] Design Theory
- [ ] Resources
- [ ] Collections
- [ ] Serialization
- [ ] Deserialization
- [ ] Pagination
- [ ] Filtering
- [ ] Caching
- [ ] Authentication
- [ ] Security
- [ ] Hypermedia Controls (HATEOAS)
- [ ] Layers of abstraction on top of RPC
- [ ] Next available actions
- [ ] Standards (JSON:API, HAL, etc.)
- [ ] Errors and Validation
- [ ] HTTP/1, HTTP/2 and HTTP/3
- [ ] HTTP/2 is a real world thing today use it
- [ ] Lets Stop Building Around a Network Hack
- [ ] Asynchronous Methodologies
- [ ] Long Polling
- [ ] Web Hooks (a.k.a Callbacks)
- [ ] WebSockets
- [ ] Message Brokers (AMQP, Kafka, etc.)
- [ ] Authentication
- Part One: Theory
- APIs, Services, and Microservices
- Understanding Different Paradigms
- API Contracts
- Design Theory
- Resources
- Collections
- Serialization
- Deserialization
- Pagination
- Filtering
- Caching
- Authentication
- Security
- Hypermedia Controls (HATEOAS)
- Layers of abstraction on top of RPC
- Next available actions
- Standards (JSON:API, HAL, etc.)
- Errors and Validation
- HTTP/1, HTTP/2 and HTTP/3
- HTTP/2 is a real world thing today use it
- Lets Stop Building Around a Network Hack
- Asynchronous Methodologies
- Long Polling
- Web Hooks (a.k.a Callbacks)
- WebSockets
- Message Brokers (AMQP, Kafka, etc.)
- Authentication

- [ ] Part Two: Planning & Design
- [x] Editors
- [x] Mocking
- [x] Documentation
- [ ] Style Guides
- Part Two: Planning & Design
- Editors
- Mocking
- Documentation
- Style Guides

- [ ] Part Three: Testing & Monitoring
- [ ] Debugging
- [ ] Traffic Inspection
- [ ] Integration Testing
- [ ] Contract Testing
- [ ] End to End / Acceptance Testing
- [ ] Health Checks
- [ ] Load Testing
- [ ] Testing in Production
- [ ] Notes on Deployment
- Part Three: Building & Testing
- Building Blocks
- Debugging
- Traffic Inspection
- Integration Testing
- Contract Testing
- End to End / Acceptance Testing
- Health Checks
- Load Testing
- Testing in Production
- Notes on Deployment

- [ ] Part Four: Management & Experience
- [ ] Portals & Documentation
- [ ] API Gateways
- [ ] Gateway Validation
- [ ] Rate Limiting
- [ ] Analytics
- [ ] Governance (Speccy / Specteral / Stoplight)
- [ ] Deprecation
- [ ] Versioning & Evolution
- Part Four: Management & Experience
- Portals & Documentation
- API Gateways
- Gateway Validation
- Rate Limiting
- Analytics
- Governance (Speccy / Specteral / Stoplight)
- Deprecation
- Versioning & Evolution

- [ ] Part Five: Further Theory
- [ ] Picking Paradigms
- [ ] Common Architectures
- [ ] REST wrapping Microservices
- [ ] Backend for Frontends (BFFs)
- Part Five: Further Theory
- Picking Paradigms
- Common Architectures
- REST wrapping Microservices
- Backend for Frontends (BFFs)

## Preview

Expand Down
48 changes: 0 additions & 48 deletions book.adoc

This file was deleted.

Binary file removed cover.jpeg
Binary file not shown.
Binary file added generated/book.epub
Binary file not shown.
Binary file added generated/book.mobi
Binary file not shown.
Binary file modified generated/book.pdf
Binary file not shown.
File renamed without changes.
File renamed without changes.
Binary file added src/1-theory/.DS_Store
Binary file not shown.
Original file line number Diff line number Diff line change
Expand Up @@ -48,7 +48,7 @@ service is just "any code that didn't fit into a model, view, or controller".
When folks talk about services in API-land, they are usually talking about
"Service-oriented Architecture".

[quote,Wikipedia,https://wikipedia.org/wiki/Service-oriented_architecture]
[quote,Wikipedia]
____
Service-oriented architecture (SOA) is a style of software design where services
are provided to the other components by application components, through a
Expand Down Expand Up @@ -153,7 +153,6 @@ some form of API, but not all APIs are a service.*
Some APIs could have a more descriptive name than service: like function, or
database.

.https://twitter.com/adamralph[Adam Ralph] at https://ndcporto.com/[NDC Porto 2019]. Photo credit https://twitter.com/dhelper[Dror Helper].
image::./images/service-is-not.jpg[Adam Ralph points out that a service with the only functionality bering a function is not a service, its a function. A service which only exposes data is a database. Adding some HTTP in front does not change its name.]

Throughout the book we will use the terms service, function and database
Expand All @@ -163,7 +162,7 @@ accordingly. Attempts will be made to disambiguate if it gets confusing.

Microservices as a term was coined around 2011. It is meant to be an off-shoot
of SoA, with more emphasis on isolation and autonomy, like the UNIX philosophy of single responsibility. Like any popular term, over time there has been
https://martinfowler.com/bliki/SemanticDiffusion.html[semantic diffusion] of the original meaning, and now there is literally meanings, common meanings, etc.
semantic diffusion of the original meaning, and now there is literally meanings, common meanings, etc.

Some folks define microservice by some objective metric, like number of
endpoints or methods - which is essentially confusing them with functions.
Expand All @@ -173,7 +172,7 @@ It is understandable, as hearing service and microservice makes you think one is
meant to be "smaller", but size in this context is not counted by the surface
area of the interface, or even the size of the entire dependency chart.

[quote,Martin Fowler and James Lewis,https://martinfowler.com/articles/microservices.html]
[quote,Martin Fowler and James Lewis]
____
In short, the microservice architectural style [1] is an approach to developing a single application as a suite of small services, each running in its own process and communicating with lightweight mechanisms, often an HTTP resource API. These services are built around business capabilities and independently deployable by fully automated deployment machinery. There is a bare minimum of centralized management of these services, which may be written in different programming languages and use different data storage technologies.
____
Expand Down
File renamed without changes.
Original file line number Diff line number Diff line change
Expand Up @@ -170,7 +170,7 @@ you can do a whole bunch of stuff:
- Automated Postman/Paw Collections

An early example of that would be SOAP, which used something called a WSDL,
something discussed in <<theory-paradigms,the previous chapter>>.
something discussed in the previous chapter.

[quote, Wikipedia]
____
Expand Down
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes
File renamed without changes
8 changes: 8 additions & 0 deletions src/1-theory/part.adoc
Original file line number Diff line number Diff line change
@@ -0,0 +1,8 @@
[part]
= Part One: Theory

include::1-apis-services-microservices.adoc[]

include::2-different-paradigms.adoc[]

include::3-api-contracts.adoc[]
Original file line number Diff line number Diff line change
Expand Up @@ -2,8 +2,8 @@

When I was younger and dumber, the planning stage for APIs was pretty much
"think of a list of endpoints then start coding". This is wildly insufficient.
As the <<1-theory/5-api-contracts#theory-contracts,API Contracts>> chapter explained, contracts are
incredibly important throughout the life-cycle of an API.
As the "API Contracts" chapter explained, contracts are incredibly important
throughout the life-cycle of an API.

The information provided in _Part One: Theory_ is going to come in useful for
this section, as we go through the actual planning of an API. During this
Expand Down
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes
File renamed without changes
File renamed without changes
File renamed without changes
10 changes: 10 additions & 0 deletions src/2-planning/part.adoc
Original file line number Diff line number Diff line change
@@ -0,0 +1,10 @@
[part]
= Part Two: Planning & Design

include::0-introduction.adoc[]

include::1-editors.adoc[]

include::2-mocking.adoc[]

include::3-documentation.adoc[]
Loading

1 comment on commit 5cda073

@cebe
Copy link
Contributor

@cebe cebe commented on 5cda073 Apr 9, 2019

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

now in 1-theory you have 3-api-contracts and 5-api-contracts :)

Please sign in to comment.