Skip to content

Commit

Permalink
fix: admonition and vocabulary
Browse files Browse the repository at this point in the history
  • Loading branch information
@alexandre-touret
alexandre-touret committed Jan 18, 2024
1 parent 46c73ba commit f34e020
Show file tree
Hide file tree
Showing 8 changed files with 143 additions and 152 deletions.
58 changes: 21 additions & 37 deletions docs/01-without_versioning.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -15,7 +15,7 @@ At this point we have our first customer : **John Doe** who uses our API with th
You must start three new shells and run [rest-book](../rest-book), [rest-number](../rest-number) and [the gateway](../gateway) modules.
As mentioned earlier, you must be at the root of the project (i.e., ``rest-apis-versioning-workshop``).

In the first shell, run:
In the first shell, **RUN**:

```jshelllanguage
./gradlew bootRun -p rest-book
Expand All @@ -27,7 +27,6 @@ In the second one:
./gradlew bootRun -p rest-number
```


And in the last one:

```jshelllanguage
Expand All @@ -36,12 +35,11 @@ And in the last one:

_You can disable unit and integration tests by adding the option ``-x test`` at the end of the command ;-)._


## The current status

### Getting the OpenAPI Documentation

You can now reach the current API documentation by running these commands:
You can now reach the current API documentation by **RUN**ning these commands:

For the books API:

Expand All @@ -54,18 +52,13 @@ For the numbers API:
http :8081/v1/v3/api-docs
```

You can also check the documentation by browsing these endpoints:

* http://localhost:8082/v1/swagger-ui/index.html
* http://localhost:8081/v1/swagger-ui/index.html

You can also use the scripts located in the [bin](../bin) folder.

Here are some examples of the functionalities provided:

* Get a Random Book

You can get a random book by running this command:
You can get a random book by **RUN**ning this command:

```jshelllanguage
. ./bin/randomBook.sh
Expand All @@ -80,12 +73,12 @@ Now you can stop this service (i.e., [rest-book](../rest-book)) now by typing CT

## Adding new data

In this chapter, we will update the [Book schema in the OpenAPI spec file](../rest-book/src/main/resources/openapi.yml) adding the attribute ``excerpt``.
In this chapter, we will **UPDATE** the [Book schema in the OpenAPI spec file](../rest-book/src/main/resources/openapi.yml) adding the attribute ``excerpt``.

This attribute is (only for the workshop) the beginning of the [description attribute](../rest-book/src/main/resources/openapi.yml).
We will extract the first 100 characters.

1. Update the [OpenAPI spec file](../rest-book/src/main/resources/openapi.yml)
1. **UPDATE** the [OpenAPI spec file](../rest-book/src/main/resources/openapi.yml)
of [the rest-book module]((../rest-book/src/main/resources/openapi.yml)) , add the ``excerpt`` attribute:

```yaml
Expand All @@ -98,7 +91,7 @@ We will extract the first 100 characters.
readOnly: true
type: string
```
2. Build the application again
2. **BUILD** the application again
```jshelllanguage
./gradlew build -p rest-book
Expand Down Expand Up @@ -140,7 +133,7 @@ public void initFields(){
}
}
```
You can now rebuild the application.
You can now re**BUILD** the application.

Before creating unit and integration tests, we can run them to see if this modification is blocking.

Expand All @@ -150,21 +143,19 @@ Before creating unit and integration tests, we can run them to see if this modif

:question: See what happens: Is it blocking or not?


5. Now, let's get a random book with an excerpt

Restart your rest-book service
Restart your rest-book service, **RUN**ing this command

```jshelllanguage
./gradlew bootRun -p rest-book
```

Check it manually by running the following command:
Check it manually by **RUN**ing the following command:

```jshelllanguage
http :8082/v1/books/1098 --print b | jq .excerpt
```

You can also do that through the API Gateway:

```jshelllanguage
Expand All @@ -174,7 +165,7 @@ http :8080/v1/books/1098 --print b | jq .excerpt

You can then add a new operation ``getBookExcerpt``.

In the [OpenAPI spec file](../rest-book/src/main/resources/openapi.yml), add a new operation:
**UPDATE** the [OpenAPI spec file](../rest-book/src/main/resources/openapi.yml), adding a new operation:

For instance:

Expand Down Expand Up @@ -220,16 +211,17 @@ For instance:

```


You can now generate the corresponding Java code.

**RUN**:

```jshelllanguage
./gradlew openApiGenerate -p rest-book
```

Now, let us create the corresponding method in [BookController](../rest-book/src/main/java/info/touret/bookstore/spring/book/controller/BookController.java):

Uncomment the following method:
**UPDATE** this class uncommenting the following method:

```java
@Override
Expand All @@ -243,7 +235,7 @@ public ResponseEntity<String> getBookExcerpt(Long id) {
}
```

Build it again:
Build it again, **RUN**:

```jshelllanguage
./gradlew build -p rest-book
Expand All @@ -253,24 +245,17 @@ You have now added new data and functionality to your API without any version :e

## What about backward compatibility?

Let's check
the [OldBookControllerIT](../rest-book/src/test/java/info/touret/bookstore/spring/book/controller/OldBookControllerIT.java)
integration test.
It uses
the [good old BookDto definition](../rest-book/src/test/java/info/touret/bookstore/spring/book/generated/dto/BookDto.java)
which represents the previous definition
of [BookDto](../rest-book/build/generated/src/main/java/info/touret/bookstore/spring/book/generated/dto/BookDto.java) (
i.e., without the ``excerpt`` functionality.
This class is based on the
first [BookDto definition](../rest-book/build/generated/src/main/java/info/touret/bookstore/spring/book/generated/dto/BookDto.java) (
i.e., without the ``exceprt`` attribute).
Let's **CHECK** the [OldBookControllerIT](../rest-book/src/test/java/info/touret/bookstore/spring/book/controller/OldBookControllerIT.java) integration test.
It uses the [good old BookDto definition](../rest-book/src/test/java/info/touret/bookstore/spring/book/generated/dto/BookDto.java) which represents the previous definition
of [BookDto](../rest-book/build/generated/src/main/java/info/touret/bookstore/spring/book/generated/dto/BookDto.java) (i.e., without the ``excerpt`` functionality.
This class is based on the first [BookDto definition](../rest-book/build/generated/src/main/java/info/touret/bookstore/spring/book/generated/dto/BookDto.java) (i.e., without the ``exceprt`` attribute).

Run it, check the log output provided by [LogBook](https://github.com/zalando/logbook/).
**RUN** it, check the log output provided by [LogBook](https://github.com/zalando/logbook/).

```jshelllanguage
./gradlew -p rest-book test
```
Check the [test log file](../rest-book/build/test-results/test/TEST-info.touret.bookstore.spring.book.controller.OldBookControllerIT.xml) and search the HTTP logs
**CHECK** the [test log file](../rest-book/build/test-results/test/TEST-info.touret.bookstore.spring.book.controller.OldBookControllerIT.xml) and search the HTTP logs

For instance:

Expand Down Expand Up @@ -308,8 +293,7 @@ For instance:

```

> **Note**
>
> [!NOTE]
> See what happens, compare the data with
> the [good old BookDto definition](../rest-book/src/test/java/info/touret/bookstore/spring/book/generated/dto/BookDto.java)
> and **explain it** :exclamation:
Expand Down
61 changes: 27 additions & 34 deletions docs/02-first_version.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -10,19 +10,17 @@
> 4. Deploy and configure a default version for your API
>


## Prerequisites
We will define in this chapter our first version in the URI and in a header mixing in the gateway & the apps.

> **Warning**
>
> [!WARNING]
> Before starting this chapter, please shut down all the apps already started:
> * [config server](../config-server)
> * [gateway](../gateway)
> * [authorization server](../authorization-server)
> * [rest-book](../rest-book)
> * [rest-number](../rest-number)
>
## URI based version

Expand All @@ -37,7 +35,7 @@ We will shortly review the configuration already done and update the OpenAPI doc

#### Rest-Book

You can check the default context path in
You can **CHECK** the default context path in
the [rest-book configuration file](../config-server/src/main/resources/config/rest-book.yml)

```yaml
Expand All @@ -46,7 +44,7 @@ server:
context-path: /v1
```
Update the [rest-book's openAPI descriptor file](../rest-book/src/main/resources/openapi.yml) adding the version in the
**UPDATE** the [rest-book's openAPI descriptor file](../rest-book/src/main/resources/openapi.yml) adding the version in the
URL:
```yaml
Expand All @@ -69,7 +67,7 @@ Now, build the project:
The same version is applied in both rest-book and rest-number modules.

To reach it, the same version has been applied to reach the rest-number module.
You can check the corresponding configuration in
You can **CHECK** the corresponding configuration in
the [rest-book configuration file](../config-server/src/main/resources/config/rest-book.yml):

```yaml
Expand All @@ -80,7 +78,7 @@ booknumbers:
#### Rest-Number
Check and modify the [rest-number's openAPI descriptor file](../rest-number/src/main/resources/openapi.yml) to indicate
**CHECK** and modify the [rest-number's openAPI descriptor file](../rest-number/src/main/resources/openapi.yml) to indicate
the version:
```yaml
Expand All @@ -92,7 +90,7 @@ servers:
- url: http://localhost:8081/v1
```
Check the [rest-number configuration file](../config-server/src/main/resources/config/rest-number.yml) and the contex
**CHECK** the [rest-number configuration file](../config-server/src/main/resources/config/rest-number.yml) and the contex
path:
```yaml
Expand All @@ -101,14 +99,14 @@ server:
context-path: /v1
```
Now, build the project:
Now, build the project, **RUN**:
```bash
./gradlew build -p rest-number
```

### In the gateway
Check the routes already defined in the [gateway application.yml configuration file](../gateway/src/main/resources/application.yml).
**CHECK** the routes already defined in the [gateway application.yml configuration file](../gateway/src/main/resources/application.yml).

```yaml
spring:
Expand Down Expand Up @@ -138,49 +136,47 @@ spring:
### Tests
#### Startup
Normally, you Docker infrastructure should be up. If not, start it:
**RUN**:
```jshelllanguage
cd infrastructure
docker compose up
```


Start then the different applications:

In the first shell:
In the first shell, **RUN**:

```jshelllanguage
./gradlew bootRun -p config-server
```
In the second shell:
In the second shell, **RUN**:

```jshelllanguage
./gradlew bootRun -p authorization-server
```

In the third shell:
In the third shell, **RUN**:

```jshelllanguage
./gradlew bootRun -p rest-book
```
In the fourth shell:
In the fourth shell, **RUN**:

```jshelllanguage
./gradlew bootRun -p rest-number
```

Last but not least, in the last one:
Last but not least, in the last one, **RUN**:

```jshelllanguage
./gradlew bootRun -p gateway
```

You can now reach the API.

For instance, you can reach the gateway:
For instance, you can reach the gateway, **RUN**ing:

```jshelllanguage
http :8080/v1/books/count
Expand All @@ -192,15 +188,15 @@ You can also access directly to the rest-book backend:
http :8082/v1/books/count
```

By the way, you can also verify if the Swagger and OpenAPI is up-to-date by browsing these endpoints:

* http://localhost:8082/v1/swagger-ui/index.html
* http://localhost:8081/v1/swagger-ui/index.html
> [!TIP]
> By the way,if you run this workshop on your local desktop, you can also verify if the Swagger and OpenAPI is up-to-date by browsing these endpoints:
> * http://localhost:8082/v1/swagger-ui/index.html
> * http://localhost:8081/v1/swagger-ui/index.html
> If you run it on GitPod, change the ``localhost:8082`` to the URL specified by the Gitpod runtime.
### Create a HTTP Header based version

In this chapter, we will put in place a rewrite/redirection mechanism in the gateway to route incoming requests
regarding a header.
In this chapter, we will put in place a rewrite/redirection mechanism in the gateway to route incoming requests regarding a header.

For this workshop we will extract the ``X-API-VERSION`` HTTP header and route to the appropriate backend.
For instance if we reach the API as following :
Expand Down Expand Up @@ -284,13 +280,12 @@ You can use now some dedicated scripts for this new approach:
Now you can test your API using either these two ways.

### Create a default version
Now let's deep dive into the gateway configuration.
Now let us deep dive into the gateway configuration.
We will configure it to apply automatically a version if no one is applied.

Stop the gateway by typing CTRL+C.

Add the following route at **THE END** of the routes definition:

**UPDATE** the following route at **THE END** of the routes definition:

```yaml
- id: default_version_v1
Expand All @@ -301,13 +296,13 @@ Add the following route at **THE END** of the routes definition:
- RewritePath=/isbns,/v1/isbns
```
Restart the gateway
Restart the gateway, **RUN**
```jshelllanguage
./gradlew bootRun -p gateway
```

and run the following command:
and **RUN** the following command:

```jshelllanguage
http :8080/isbns
Expand All @@ -321,9 +316,7 @@ In this chapter we have seen how to specify and deal with API version numbers in
The [gateway configuration](../gateway/src/main/resources/application.yml) is intentionally simple and minimalistic.
In _the real life_ we would code a dynamic routing and filtering mechanism.


> **Note**
>
> [!NOTE]
> In your opinion, which way is the best: URI, HTTP header, Accept HTTP header? And where: in the gateway or in the backend? or both?
>
> [Go then to chapter 3](./03-second_version.md)
Loading

0 comments on commit f34e020

Please sign in to comment.