[REST API] Incorporate changes related to REST API docs (#900)

README.md

@@ -26,13 +26,13 @@ Book a [1-on-1 Session](https://cal.com/taranjeetio/ec) with Taranjeet, the foun
 pip install --upgrade embedchain
 ```
 
-To run Embedchain as a REST API server use,
+To run Embedchain as a REST API server run the following command:
 
 ```bash
-docker run -d --name embedchain -p 8000:8000 embedchain/app:rest-api-latest
+docker run -d --name embedchain -p 8080:8080 embedchain/app:rest-api-latest
 ```
 
-Navigate to http://0.0.0.0:8000/docs to interact with the API.
+Navigate to http://0.0.0.0:8080/docs to interact with the API.
 
 ## 🔍 Demo
 

docs/api-reference/add-datasource-to-an-app.mdx

@@ -1,3 +0,0 @@
----
-openapi: post /{app_id}/add
----

docs/api-reference/deploy-app.mdx

@@ -1,3 +0,0 @@
----
-openapi: post /{app_id}/deploy
----

docs/api-reference/getting-started.mdx

@@ -7,10 +7,10 @@ title: "🌍 Getting Started"
 To run Embedchain as a REST API server use,
 
 ```bash
-docker run -d --name embedchain -p 8000:8000 embedchain/app:rest-api-latest
+docker run -d --name embedchain -p 8080:8080 embedchain/app:rest-api-latest
 ```
 
-Open up your browser and navigate to http://0.0.0.0:8000/docs to interact with the API. There is a full-fledged Swagger docs playground with all the information
+Open up your browser and navigate to http://0.0.0.0:8080/docs to interact with the API. There is a full-fledged Swagger docs playground with all the information
 about the API endpoints.
 
 ![Swagger Docs Screenshot](https://github.com/embedchain/embedchain/assets/73601258/299d81e5-a0df-407c-afc2-6fa2c4286844)
@@ -83,7 +83,7 @@ To provide them, you can simply run the docker command with the `-e` flag.
 For example,
 
 ```bash
-docker run -d --name embedchain -p 8000:8000 -e OPENAI_API_KEY=YOUR_API_KEY embedchain/app:rest-api-latest
+docker run -d --name embedchain -p 8080:8080 -e OPENAI_API_KEY=YOUR_API_KEY embedchain/app:rest-api-latest
 ```
 
 Cool! This will create a new Embedchain App with the given `app_id`.

docs/mint.json

@@ -92,7 +92,7 @@
       "pages": ["advanced/configuration"]
     },
     {
-      "group": "Rest API",
+      "group": "REST API",
         "pages": [
           "api-reference/getting-started",
           "api-reference/check-status",
@@ -161,5 +161,8 @@
   },
   "search": {
     "prompt": "✨ Search embedchain docs..."
+  },
+  "api": {
+    "baseUrl": "http://localhost:8080"
   }
 }

docs/rest-api.json

@@ -13,8 +13,8 @@
       "/ping": {
         "get": {
           "tags": ["Utility"],
-          "summary": "Check Status",
+          "summary": "Check status",
-          "description": "Endpoint to check the status of the API.",
+          "description": "Endpoint to check the status of the API",
           "operationId": "check_status_ping_get",
           "responses": {
             "200": {
@@ -27,8 +27,8 @@
       "/apps": {
         "get": {
           "tags": ["Apps"],
-          "summary": "Get All Apps",
+          "summary": "Get all apps",
-          "description": "Get all apps.",
+          "description": "Get all applications",
           "operationId": "get_all_apps_apps_get",
           "responses": {
             "200": {
@@ -41,8 +41,8 @@
       "/create": {
         "post": {
           "tags": ["Apps"],
-          "summary": "Create App",
+          "summary": "Create app",
-          "description": "Create a new app using App ID.",
+          "description": "Create a new app using App ID",
           "operationId": "create_app_using_default_config_create_post",
           "parameters": [
             {
@@ -89,8 +89,8 @@
       "/{app_id}/data": {
         "get": {
           "tags": ["Apps"],
-          "summary": "Get Datasources Associated With App Id",
+          "summary": "Get data",
-          "description": "Get all datasources for an app.",
+          "description": "Get all data sources for an app",
           "operationId": "get_datasources_associated_with_app_id__app_id__data_get",
           "parameters": [
             {
@@ -119,8 +119,8 @@
       "/{app_id}/add": {
         "post": {
           "tags": ["Apps"],
-          "summary": "Add Datasource To An App",
+          "summary": "Add data",
-          "description": "Add a source to an existing app.",
+          "description": "Add a data source to an app.",
           "operationId": "add_datasource_to_an_app__app_id__add_post",
           "parameters": [
             {
@@ -161,8 +161,8 @@
       "/{app_id}/query": {
         "post": {
           "tags": ["Apps"],
-          "summary": "Query An App",
+          "summary": "Query app",
-          "description": "Query an existing app.",
+          "description": "Query an app",
           "operationId": "query_an_app__app_id__query_post",
           "parameters": [
             {
@@ -203,8 +203,8 @@
       "/{app_id}/chat": {
         "post": {
           "tags": ["Apps"],
-          "summary": "Chat With An App",
+          "summary": "Chat",
-          "description": "Query an existing app.\n\napp_id: The ID of the app. Use \"default\" for the default app.\n\nmessage: The message that you want to send to the App.",
+          "description": "Chat with an app.\n\napp_id: The ID of the app. Use \"default\" for the default app.\n\nmessage: The message that you want to send to the app.",
           "operationId": "chat_with_an_app__app_id__chat_post",
           "parameters": [
             {
@@ -287,8 +287,8 @@
       "/{app_id}/delete": {
         "delete": {
           "tags": ["Apps"],
-          "summary": "Delete App",
+          "summary": "Delete app",
-          "description": "Delete an existing app.",
+          "description": "Delete an existing app",
           "operationId": "delete_app__app_id__delete_delete",
           "parameters": [
             {
@@ -339,7 +339,7 @@
             "api_key": {
               "type": "string",
               "title": "Api Key",
-              "description": "The Embedchain API key for App deployments.",
+              "description": "The Embedchain API key for app deployments. You get the api key on the Embedchain platform by visiting [https://app.embedchain.ai](https://app.embedchain.ai)",
               "default": ""
             }
           },
@@ -425,4 +425,3 @@
       }
     }
   }
-  

docs/rest-api/add-data.mdx

@@ -0,0 +1,22 @@
+---
+openapi: post /{app_id}/add
+---
+
+<RequestExample>
+
+```bash Request
+curl --request POST \
+  --url http://localhost:8080/{app_id}/add \
+  -d "source=https://www.forbes.com/profile/elon-musk" \
+  -d "data_type=web_page"
+```
+
+</RequestExample>
+
+<ResponseExample>
+
+```json Response
+{ "response": "fec7fe91e6b2d732938a2ec2e32bfe3f" }
+```
+
+</ResponseExample>

docs/rest-api/chat.mdx

@@ -0,0 +1,3 @@
+---
+openapi: post /{app_id}/chat
+---

docs/rest-api/check-status.mdx

@@ -0,0 +1,20 @@
+---
+openapi: get /ping
+---
+
+<RequestExample>
+
+```bash Request
+  curl --request GET \
+    --url http://localhost:8080/ping
+```
+
+</RequestExample>
+
+<ResponseExample>
+
+```json Response
+{ "ping": "pong" }
+```
+
+</ResponseExample>

docs/rest-api/create.mdx

@@ -0,0 +1,21 @@
+---
+openapi: post /create
+---
+
+<RequestExample>
+
+```bash Request
+curl --request POST \
+  --url http://localhost:8080/create \
+  -F "config=@/path/to/config.yaml"
+```
+
+</RequestExample>
+
+<ResponseExample>
+
+```json Response
+{ "response": "App created successfully. App ID: {app_id}" }
+```
+
+</ResponseExample>

docs/rest-api/delete.mdx

@@ -0,0 +1,21 @@
+---
+openapi: delete /{app_id}/delete
+---
+
+
+<RequestExample>
+
+```bash Request
+  curl --request DELETE \
+    --url http://localhost:8080/{app_id}/delete
+```
+
+</RequestExample>
+
+<ResponseExample>
+
+```json Response
+{ "response": "App with id {app_id} deleted successfully." }
+```
+
+</ResponseExample>

docs/rest-api/deploy.mdx

@@ -0,0 +1,22 @@
+---
+openapi: post /{app_id}/deploy
+---
+
+
+<RequestExample>
+
+```bash Request
+curl --request POST \
+  --url http://localhost:8080/{app_id}/deploy \
+  -d "api_key=ec-xxxx"
+```
+
+</RequestExample>
+
+<ResponseExample>
+
+```json Response
+{ "response": "App deployed successfully." }
+```
+
+</ResponseExample>

docs/rest-api/get-all-apps.mdx

@@ -0,0 +1,33 @@
+---
+openapi: get /apps
+---
+
+<RequestExample>
+
+```bash Request
+curl --request GET \
+  --url http://localhost:8080/apps
+```
+
+</RequestExample>
+
+<ResponseExample>
+
+```json Response
+{
+  "results": [
+    {
+      "config": "config1.yaml",
+      "id": 1,
+      "app_id": "app1"
+    },
+    {
+      "config": "config2.yaml",
+      "id": 2,
+      "app_id": "app2"
+    }
+  ]
+}
+```
+
+</ResponseExample>

docs/rest-api/get-data.mdx

@@ -0,0 +1,28 @@
+---
+openapi: get /{app_id}/data
+---
+
+<RequestExample>
+
+```bash Request
+curl --request GET \
+  --url http://localhost:8080/{app_id}/data
+```
+
+</RequestExample>
+
+<ResponseExample>
+
+```json Response
+{
+  "results": [
+    {
+      "data_type": "web_page",
+      "data_value": "https://www.forbes.com/profile/elon-musk/",
+      "metadata": "null"
+    }
+  ]
+}
+```
+
+</ResponseExample>

docs/rest-api/getting-started.mdx

@@ -0,0 +1,87 @@
+---
+title: "🌍 Getting Started"
+---
+
+## Quickstart
+
+To use Embedchain as a REST API service, run the following command:
+
+```bash
+docker run --name embedchain -p 8080:8080 embedchain/app:rest-api-latest
+```
+
+Navigate to [http://localhost:8080/docs](http://localhost:8080/docs) to interact with the API. There is a full-fledged Swagger docs playground with all the information about the API endpoints.
+
+![Swagger Docs Screenshot](https://github.com/embedchain/embedchain/assets/73601258/299d81e5-a0df-407c-afc2-6fa2c4286844)
+
+## Creating your first App
+
+App requires an `app_id` to be created. The `app_id` is a unique identifier for your app. By default we will use the opensource **gpt4all** model to get started. You can also specify your own config by uploading a config YAML file.
+
+For example, create a `config.yaml` file (adjust according to your requirements):
+
+```yaml
+app:
+  config:
+    id: "default-app"
+
+llm:
+  provider: openai
+  config:
+    model: "gpt-3.5-turbo"
+    temperature: 0.5
+    max_tokens: 1000
+    top_p: 1
+    stream: false
+    template: |
+      Use the following pieces of context to answer the query at the end.
+      If you don't know the answer, just say that you don't know, don't try to make up an answer.
+
+      $context
+
+      Query: $query
+
+      Helpful Answer:
+
+vectordb:
+  provider: chroma
+  config:
+    collection_name: "rest-api-app"
+    dir: db
+    allow_reset: true
+
+embedder:
+  provider: openai
+  config:
+    model: "text-embedding-ada-002"
+```
+
+To learn more about custom configurations, check out the [custom configurations docs](https://docs.embedchain.ai/advanced/configuration). To explore more examples of config yamls for embedchain, visit [embedchain/configs](https://github.com/embedchain/embedchain/tree/main/configs).
+
+Now, you can upload this config file in the request body.
+
+**Note:** To use custom models, an **API key** might be required. Refer to the table below to determine the necessary API key for your provider.
+
+| Keys                       | Providers                      |
+| -------------------------- | ------------------------------ |
+| `OPENAI_API_KEY `          | OpenAI, Azure OpenAI, Jina etc |
+| `OPENAI_API_TYPE`          | Azure OpenAI                   |
+| `OPENAI_API_BASE`          | Azure OpenAI                   |
+| `OPENAI_API_VERSION`       | Azure OpenAI                   |
+| `COHERE_API_KEY`           | Cohere                         |
+| `ANTHROPIC_API_KEY`        | Anthropic                      |
+| `JINACHAT_API_KEY`         | Jina                           |
+| `HUGGINGFACE_ACCESS_TOKEN` | Huggingface                    |
+| `REPLICATE_API_TOKEN`      | LLAMA2                         |
+
+To add env variables, you can simply run the docker command with the `-e` flag.
+
+For example,
+
+```bash
+docker run --name embedchain -p 8080:8080 -e OPENAI_API_KEY=<YOUR_OPENAI_API_KEY> embedchain/app:rest-api-latest
+```
+
+If you run into issues, please feel free to contact us using below links:
+
+<Snippet file="get-help.mdx" />

docs/rest-api/query.mdx

@@ -0,0 +1,21 @@
+---
+openapi: post /{app_id}/query
+---
+
+<RequestExample>
+
+```bash Request
+curl --request POST \
+  --url http://localhost:8080/{app_id}/query \
+  -d "query=who is Elon Musk?"
+```
+
+</RequestExample>
+
+<ResponseExample>
+
+```json Response
+{ "response": "Net worth of Elon Musk is $218 Billion." }
+```
+
+</ResponseExample>

examples/rest-api/Dockerfile

@@ -8,8 +8,8 @@ RUN pip install --no-cache-dir -r requirements.txt
 
 COPY . /app
 
-EXPOSE 8000
+EXPOSE 8080
 
 ENV NAME embedchain
 
-CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8000"]
+CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8080"]

examples/rest-api/README.md

@@ -1,7 +1,7 @@
 ## Single command to rule them all,
 
 ```bash
-docker run -d --name embedchain -p 8000:8000 embedchain/app:rest-api-latest
+docker run -d --name embedchain -p 8080:8080 embedchain/app:rest-api-latest
 ```
 
 ### To run the app locally,
@@ -15,7 +15,7 @@ Using docker (locally),
 
 ```bash
 docker build -t embedchain/app:rest-api-latest .
-docker run -d --name embedchain -p 8000:8000 embedchain/app:rest-api-latest
+docker run -d --name embedchain -p 8080:8080 embedchain/app:rest-api-latest
 docker image push embedchain/app:rest-api-latest
 ```
 

examples/rest-api/bruno/ec-rest-api/default_add.bru

@@ -5,7 +5,7 @@ meta {
 }
 
 post {
-  url: http://localhost:8000/add
+  url: http://localhost:8080/add
   body: json
   auth: none
 }

examples/rest-api/bruno/ec-rest-api/default_chat.bru

@@ -5,7 +5,7 @@ meta {
 }
 
 post {
-  url: http://localhost:8000/chat
+  url: http://localhost:8080/chat
   body: json
   auth: none
 }

examples/rest-api/bruno/ec-rest-api/default_query.bru

@@ -5,7 +5,7 @@ meta {
 }
 
 post {
-  url: http://localhost:8000/query
+  url: http://localhost:8080/query
   body: json
   auth: none
 }

examples/rest-api/bruno/ec-rest-api/ping.bru

@@ -5,7 +5,7 @@ meta {
 }
 
 get {
-  url: http://localhost:8000/ping
+  url: http://localhost:8080/ping
   body: json
   auth: none
 }

examples/rest-api/main.py

@@ -39,7 +39,7 @@ app = FastAPI(
 @app.get("/ping", tags=["Utility"])
 def check_status():
     """
-    Endpoint to check the status of the API.
+    Endpoint to check the status of the API
     """
     return {"ping": "pong"}
 
@@ -85,7 +85,7 @@ async def create_app_using_default_config(app_id: str, config: UploadFile = None
 
         return DefaultResponse(response=f"App created successfully. App ID: {app_id}")
     except Exception as e:
-        raise HTTPException(detail=f"Error creating app: {e}", status_code=400)
+        raise HTTPException(detail=f"Error creating app: {str(e)}", status_code=400)
 
 
 @app.get(
@@ -94,7 +94,7 @@ async def create_app_using_default_config(app_id: str, config: UploadFile = None
 )
 async def get_datasources_associated_with_app_id(app_id: str, db: Session = Depends(get_db)):
     """
-    Get all datasources for an app.\n
+    Get all data sources for an app.\n
     app_id: The ID of the app. Use "default" for the default app.\n
     """
     try:
@@ -120,7 +120,7 @@ async def get_datasources_associated_with_app_id(app_id: str, db: Session = Depe
                 status_code=400,
             )
     except Exception as e:
-        raise HTTPException(detail=f"Error occurred: {e}", status_code=400)
+        raise HTTPException(detail=f"Error occurred: {str(e)}", status_code=400)
 
 
 @app.post(
@@ -158,7 +158,7 @@ async def add_datasource_to_an_app(body: SourceApp, app_id: str, db: Session = D
                 status_code=400,
             )
     except Exception as e:
-        raise HTTPException(detail=f"Error occurred: {e}", status_code=400)
+        raise HTTPException(detail=f"Error occurred: {str(e)}", status_code=400)
 
 
 @app.post(
@@ -195,7 +195,7 @@ async def query_an_app(body: QueryApp, app_id: str, db: Session = Depends(get_db
                 status_code=400,
             )
     except Exception as e:
-        raise HTTPException(detail=f"Error occurred: {e}", status_code=400)
+        raise HTTPException(detail=f"Error occurred: {str(e)}", status_code=400)
 
 
 # FIXME: The chat implementation of Embedchain needs to be modified to work with the REST API.
@@ -236,7 +236,7 @@ async def query_an_app(body: QueryApp, app_id: str, db: Session = Depends(get_db
 #                 status_code=400,
 #             )
 #     except Exception as e:
-#         raise HTTPException(detail=f"Error occurred: {e}", status_code=400)
+#         raise HTTPException(detail=f"Error occurred: {str(e)}", status_code=400)
 
 
 @app.post(
@@ -278,7 +278,7 @@ async def deploy_app(body: DeployAppRequest, app_id: str, db: Session = Depends(
                 status_code=400,
             )
     except Exception as e:
-        raise HTTPException(detail=f"Error occurred: {e}", status_code=400)
+        raise HTTPException(detail=f"Error occurred: {str(e)}", status_code=400)
 
 
 @app.delete(
@@ -311,11 +311,11 @@ async def delete_app(app_id: str, db: Session = Depends(get_db)):
         remove_app(db, app_id)
         return DefaultResponse(response=f"App with id {app_id} deleted successfully.")
     except Exception as e:
-        raise HTTPException(detail=f"Error occurred: {e}", status_code=400)
+        raise HTTPException(detail=f"Error occurred: {str(e)}", status_code=400)
 
 
 if __name__ == "__main__":
     import uvicorn
 
     is_dev = os.getenv("DEVELOPMENT", "False")
-    uvicorn.run("main:app", host="0.0.0.0", port=8000, reload=bool(is_dev))
+    uvicorn.run("main:app", host="0.0.0.0", port=8080, reload=bool(is_dev))