chore: Api schema change documentation (#53)

* chore: update api docs * chore: reconciliation api documentation --------- Co-authored-by: gagan.dhand <[email protected]>
goto · Jul 26, 2024 · 756f9e0 · 756f9e0
1 parent 4c5dee5
commit 756f9e0
Show file tree

Hide file tree

Showing 5 changed files with 57 additions and 1 deletion.
diff --git a/docs/docs/guides/1_quickstart.md b/docs/docs/guides/1_quickstart.md
@@ -170,6 +170,10 @@ $ curl -X GET http://localhost:8000/v1beta1/namespaces/quickstart/schemas/exampl
 
 # Download latest version of particular schema
 $ curl -X GET http://localhost:8000/v1beta1/namespaces/quickstart/schemas/example;
+
+# Reconciliation API
+$ curl -X GET http://localhost:8080/v1beta1/schema/detect-change/quickstart/example?from=1&to=2;
+
 ```
 
 </TabItem>

diff --git a/docs/docs/guides/3_manage_schemas.md b/docs/docs/guides/3_manage_schemas.md
@@ -65,3 +65,8 @@ curl -X GET http://localhost:8000/v1beta1/namespaces/quickstart/schemas/example/
 # upload schema can be called multiple times. Stencil server will retain old version if it's already uploaded. This call won't create new version again. You can verify by using versions API again.
 curl -H "X-SourceURL:www.github.com/some-repo" -H "X-CommitSHA:some-commit-sha" -X POST http://localhost:8000/v1/namespaces/quickstart/schemas --data-binary "@file.desc"
 ```
+
+## Reconciliation API
+```bash
+$ curl -X GET http://localhost:8080/v1beta1/schema/detect-change/quickstart/example?from=1&to=2;
+```
diff --git a/docs/docs/guides/5_schema_change.md b/docs/docs/guides/5_schema_change.md
@@ -43,7 +43,7 @@ Now, when the schema is uploaded in DB. Below things happened parallely in separ
 
 In case of any failure while publishing to Kafka or other issues, the `notification_events` table can be utilized to
 manage these failures. If the `success` field is `false` for a specific `namespace_id`, `schema_id`, and `version_id`,
-it indicates that the notification was not sent. In such scenarios, the `reconciliation API` can be used to resend the
+it indicates that the notification was not sent. In such scenarios, the [Reconciliation API](../reference/api.md#reconciliation-api) can be used to resend the
 notifications.
 
 ## Depth
@@ -101,3 +101,8 @@ E.g. If depth is `2` then the `impacted_schemas` for `Address` in below sample w
 
 ## Showing MR information 
 While calculating the impacted schemas, the `SchemaChangedEvent` will also include information about the source URL and commit SHA. The `source_url` represents the repository URL, and the `commit_sha` corresponds to the commit SHA associated with that version.
+
+## Reconciliation API
+```bash
+$ curl -X GET http://localhost:8080/v1beta1/schema/detect-change/quickstart/example?from=1&to=2;
+```
diff --git a/docs/docs/reference/api.md b/docs/docs/reference/api.md
@@ -334,6 +334,45 @@ Global Search API
 | 200     | A successful response.        | [v1beta1SearchResponse](#v1beta1searchresponse) |
 | default | An unexpected error response. | [rpcStatus](#rpcstatus)                         |
 
+### Reconciliation API
+
+#### /v1beta1/schema/detect-change/{namespaceId}/{schemaName}?from={v1}&to={v2}
+
+#### GET
+
+##### Summary
+
+Detect Schema Change for the given version i.e v1 and v2.
+
+##### Parameters
+
+| Name        | Located in | Description                                    | Required | Schema  |
+|-------------|------------|------------------------------------------------|----------|---------|
+| namespaceId | path       |                                                | Yes      | string  |
+| schemaName  | path       |                                                | Yes      | string  |
+| from        | queryParam | version from which change has to be calculated | No       | integer |
+| to          | queryParam | version to which change has to be calculated   | No       | integer |
+
+##### Different cases and validation of `from` and `to` version
+
+| S. No. | From | To     | From (In Code) | To (In Code) | Error                                    |
+|--------|------|--------|----------------|--------------|------------------------------------------|
+| 1.     | “”   | “”     | latest-1       | latest       | N/A                                      |
+| 2.     | “”   | latest | latest-1       | latest       | N/A                                      |
+| 3.     | “”   | 42     | 41             | 42           | N/A                                      |
+| 4.     | 41   | “”     | 41             | latest       | N/A                                      |
+| 5.     | 41   | 42     | 41             | 42           | N/A                                      |
+| 6.     | 41   | 45     | 41             | 45           | N/A                                      |
+| 7.     | 41   | 40     | -              | -            | Bad Request: From should be less than To |
+| 8.     | 41   | 41     | -              | -            | Bad Request: From should be less than To |
+
+##### Responses
+
+| Code    | Description                   | Schema                                                  |
+|---------|-------------------------------|---------------------------------------------------------|
+| 200     | A successful response.        | [v1beta1SchemaChangedEvent](#v1beta1SchemaChangedEvent) |
+| default | An unexpected error response. | [rpcStatus](#rpcstatus)                                 |
+
 ### Models
 
 #### SchemaCompatibility

diff --git a/docs/docs/server/overview.md b/docs/docs/server/overview.md
@@ -121,4 +121,7 @@ curl -X GET http://localhost:8000/v1beta1/namespaces/quickstart/schemas/example/
 
 # upload schema can be called multiple times. Stencil server will retain old version if it's already uploaded. This call won't create new version again. You can verify by using versions API again.
 curl -H "X-SourceURL:www.github.com/some-repo" -H "X-CommitSHA:some-commit-sha" -X POST http://localhost:8000/v1/namespaces/quickstart/schemas --data-binary "@file.desc"
+
+# Reconciliation API
+curl -X GET http://localhost:8080/v1beta1/schema/detect-change/quickstart/example?from=1&to=2;
 ```