documentation improvements

00-apiclarity-overview.md

@@ -1,3 +1,20 @@
-# 00. Apiclarity overview
+# 00. APIClarity overview
 
-<!-- TO DO -->
+Open source for API traffic visibility in K8s clusters
+
+## Microservices API challenges
+Microservice applications interact via API’s with many other applications. To minimize risk, it is valuable to have visibility to the OpenAPI specifications and to understand any potential changes to that specification throughout the application lifecycle. However, obtaining OpenAPI specs can be challenging, particularly for external or legacy applications.
+
+Proper OpenAPI specifications can be further complicated by microservices that use deprecated APIs (a.k.a. Zombie APIs)​ or microservices that use undocumented APIs (a.k.a. Shadow APIs).
+
+Finally, it’s important to be able to obtain Open API specifications without code instrumentation or modifying existing workloads.
+
+## Solution
+
+* Capture all API traffic in an existing environment using a service-mesh framework​
+* Construct the OpenAPI specification by observing the API traffic
+* Allow the User to upload OpenAPI spec, review, modify and approve generated OpenAPI specs​
+* Alert the user on any difference between the approved API specification and the one that is observed in runtime, detects shadow & zombie APIs​​
+* UI dashboard to audit and monitor the API findings
+
+![](images/apiclarity-docs-diagram.jpeg)

02.apiclarity-setup.md

@@ -1,18 +1,27 @@
-# 02. Apiclarity setup
+# 02. APIClarity setup
+
+Follow these few steps to install APIClarity on your kubernetes cluster.
 
 ## Task 1. Create a labeled/protected namespace
 
+APIClarity will use istio to monitor application traffic.
+Create a dedicated namespace for the user application.
+Add an istio-injection label so that istio automatically inserts envoy proxy to the user application.
+
 ```bash
 kubectl create namespace bookinfo
 kubectl label namespace bookinfo istio-injection=enabled --overwrite
 ```
 
-## Task 2. Install Apiclarity
+## Task 2. Install APIClarity
 
 ```bash
 helm repo add apiclarity https://openclarity.github.io/apiclarity
 ```
 
+Specify that envoy (Istio) is used to monitor for API traffic.
+Don't forget to specify which namespaces are monitored by APIClarity.
+
 ```bash
 helm install \
 --set trafficSource.envoyWasm.enabled=true \

03.application-api-analysis.md

@@ -1,6 +1,32 @@
 # 03. Application API analysis
 
-## Task 3. Deploy BookInfo Application
+Now, let's install the user application bookinfo.
+
+The application displays information about a book, similar to a single catalog entry of an online book store. Displayed on the page is a description of the book, book details (ISBN, number of pages, and so on), and a few book reviews.
+
+The Bookinfo application is broken into four separate microservices:
+
+* productpage. The productpage microservice calls the details and reviews microservices to populate the page.
+* details. The details microservice contains book information.
+* reviews. The reviews microservice contains book reviews. It also calls the ratings microservice.
+* ratings. The ratings microservice contains book ranking information that accompanies a book review.
+
+There are 3 versions of the reviews microservice:
+
+* Version v1 doesn’t call the ratings service.
+* Version v2 calls the ratings service, and displays each rating as 1 to 5 black stars.
+* Version v3 calls the ratings service, and displays each rating as 1 to 5 red stars.
+
+The end-to-end architecture of the application is shown below.
+
+![](images/booinfo-istio.svg)
+
+As the application architecture is based on micro-services which use REST APIs for inter communication,
+APIClarity can analyse it.
+
+[Locust](https://docs.locust.io/en/stable/#) is deployed as part of the application to simulate periodic user requests.
+
+## Task 1. Deploy BookInfo Application
 
 Run the following command to install the BookInfo application:
 
@@ -29,13 +55,15 @@ configmap/reviews-inject-config created
 deployment.apps/reviews-inject-v1 created
 ```
 
-## Task 4. Analyse API traffic on APIClarity
+## Task 2. Analyse API traffic on APIClarity
 
 Open the web UI of APIClarity. Refresh the page if you don't find captured traffic.
 
+Observe the graph. Multiple user requests are automcatically simulated. This generates several hundreds of API calls every second. None of the detected calls are known by APIClarity. Thus, they are defined as *New APIs*.
+
 ![](./images/2022-10-26-14-26-51.png)
 
-## Task 5. Reconstruct API schema.
+## Task 3. Reconstruct API schema.
 
 Under the API inventory you will find three discovered APIs:
 
@@ -64,10 +92,9 @@ Once the schema is generated, you can review it in Swagger.
 
 ![](./images/2022-10-26-14-34-23.png)
 
-## Task 6. Analysis of API difference
+## Task 4. Analysis of API difference
 
-Once a schema is loaded by the user or reconstructed by APIClarity,
-The application is using to compare running traffic towards the blueprint.
+Once a schema is loaded by the user or reconstructed by APIClarity, the application is using to compare running traffic towards the blueprint.
 
 Use the API Events page to find for traffic which does not respect the schema:
 
@@ -77,4 +104,4 @@ Review an event with alert.
 
 ![](./images/2022-10-26-14-37-52.png)
 
-To approve the diff,
+You will find that this particular API call does not respect the generated schema - several parameters are missing.

README.md

@@ -1,7 +1,9 @@
-# Skeleton for creating a new demo/lab content:
+# APIClarity Basics
+
+![](images/logo-light-horizantal-svg.svg)
+
+Get your hands on APIClarity. You will find instructions to:
+- [Install a dedicated kubernetes cluster with Istio (service mesh) and Calico (CNI)](01.kubernetes-setup.md)
+- [Install APIClarity](02.apiclarity-setup.md)
+- [Run an application (bookinfo) and analyse the API traffic using APIClarity](03.application-api-analysis.md)
 
-- put your .md files in the root of the repo - they will be taken in alphabetical order, maybe a good idea to start with numbers, like 01..., 02....
-- any images you use in your md files should be put in the images folder
-- put the needed files/scripts/code for the lab inside the content folder. the contents of that folder will be copied in the home directory of the lab user
-
-the current file (README.md) will be ignored on the demo platform.