Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

ENDOC-653 update Access Entando APIs #678

Merged
merged 3 commits into from
Feb 17, 2023
Merged

ENDOC-653 update Access Entando APIs #678

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
87bb241
ENDOC-653 update Access Entando APIs
jyunmitch Feb 8, 2023
476afac
ENDOC-653 review edits
jyunmitch Feb 16, 2023
0073790
ENDOC-653 last edits
jyunmitch Feb 17, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
153 changes: 46 additions & 107 deletions vuepress/docs/next/docs/consume/entando-apis.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,139 +3,78 @@ sidebarDepth: 2
---
# Accessing Entando APIs

## Overview

Entando includes the Swagger UI in a quickstart environment and is reachable at `/entando-de-app/api/swagger-ui.html`:
Entando includes the Swagger UI for API access in a quickstart environment. This document presents an overview and instructions on how to enable and access the Swagger UI.

http://[your-host-name]/entando-de-app/api/swagger-ui.html

### Enable or disable the Swagger UI in a running container

The Swagger UI can be enabled or disabled in a running container by modifying the SPRING_PROFILES_ACTIVE environment variable for the entando-de-app container.

1. Edit the deployment. The name may be different outside of a quickstart environment. Note: Use the [ent CLI](../getting-started/entando-cli.md) to send commands to Kubernetes from the host machine.
```
kubectl -n entando edit deployment/quickstart-server-deployment
```

2. (Optional) Scale the deployment `spec.replicas` to 0 before updating the deployment. This is necessary if you're using an in-memory database, e.g. the default quickstart configuration, and will prevent database errors that can happen on an immediate restart after the profile is changed. Save the deployment to apply the change.

3. Find the entando-de-app env variables section under `spec.template.spec.containers.env[image: entando-de-app]`

4a. To enable the swagger UI, add the SPRING_PROFILES_ACTIVE environment variable, if it's missing, or add `swagger` to its comma-delimited list.

```
- name: SPRING_PROFILES_ACTIVE
value: default,swagger
```
4b. To disable the swagger UI, remove `swagger` from the value.

5. (Optional) Reset the deployment `spec.replicas` back to 1.

6. Save the deployment to apply the change.

## How to find your client secret
You'll need your client credentials to execute the Entando APIs.

1. Login into your Keycloak instance

2. Go to `Administration → Clients`

3. Select the desired client (e.g. in a quickstart environment this is `quickstart-server`)

4. Click on the `Credentials` tab to get the secret

## Setup in local environment

You may prefer to run a local standalone Entando application for some tasks. You'll need Java 11, maven, and Keycloak for authentication. See [these instructions](https://github.com/entando/app-builder/blob/master/with-keycloak.md) to setup a standalone Keycloak.

### Configure Keycloak

Configure your Keycloak client in order to support Swagger UI. A quickstart environment has this pre-configured.

1. Login to your Keycloak instance

2. Access the Administration console

3. Click on `Clients` on the left bar and select your client (e.g. `quickstart-server`)
## APIs Overview
The Entando App Engine uses REST APIs to enact all the functionality inside the App Builder. For example, APIs are used to add widgets to a page or create components like pages and page templates. APIs can also be used to support automation, testing, and integration with external systems.
Copy link
Contributor

Choose a reason for hiding this comment

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

could enact -> execute? seems to be more precise and the usual language?

Copy link
Collaborator Author

Choose a reason for hiding this comment

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

I think enact is fine here, especially as APIs don't really execute things as they just move information back and forth


4. Update the following values under `Settings`:
- Set `Valid Redirect URIs` to `http://localhost:[your port]/entando-de-app/*` or `*` to allow all redirect URIs.
- Set `Web Origins` to `http://localhost:[your port]` or `*` to accept all origins.
## API Structure
All the APIs share a common top-level structure. Each response contains a top level entry for `errors`, `metadata`, and `payload`.

### Start the Entando Application
The `errors` contain code and a message string indicating the error condition of the request. The `metadata` section is used for paging, sorting, and filtering data not included in the body. The body of each response is included in the payload section and varies according to each API.

1. Clone the Entando reference application:
## Models
All of the model classes returned by the Entando App Engine are annotated with definitions included in the Swagger documentation. They are listed at the bottom of the Swagger page.

git clone https://github.com/entando/entando-de-app
## Enable the Swagger UI

2. Start the application with the following options:

- Enable the Swagger profile via `-Dspring.profiles.active=swagger`
- Enable the Keycloak profile via `-Pkeycloak`
- Configure the application connection to Keycloak itself. For simplicity this uses the same client credentials you'll use to try out the APIs.
- Set `-Dkeycloak.auth.url` to your Keycloak endpoint (including `/auth`), e.g. `-Dkeycloak.auth.url=http://my-keycloak-server/auth`
- Set `-Dkeycloak.client.id` to your client id, e.g. `-Dkeycloak.client.id=quickstart-server`
- Set `-Dkeycloak.client.secret` to your client secret, e.g. `-Dkeycloak.client.secret=my-secret`. See [How to find your client secret](#how-to-find-your-client-secret) above.
- (Optional) Set`-Djetty.port=8085` if the default port 8080 is already in use.
- (Optional) To skip the docker steps (or if you don't have docker installed/running), add `-DskipDocker=true`

Here's a full example:

mvn clean package jetty:run-war -Pjetty-local -Pderby -Pkeycloak -Dspring.profiles.active=swagger -Djetty.port=8085 -Dorg.slf4j.simpleLogger.log.org.eclipse.jetty.annotations.AnnotationParser=error -Dkeycloak.auth.url=http://my-keycloak-host/auth -Dkeycloak.client.id=quickstart-server -Dkeycloak.client.secret=my-client-secret -DskipDocker=true
The Swagger UI can be enabled or disabled in a running Entando instance by modifying the `SPRING_PROFILES_ACTIVE` environment variable for the `entando-de-app` container.
Copy link
Contributor

Choose a reason for hiding this comment

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

would reorder like above to set the scene for the reader by starting with the applicable env: "In a running Entando instance, the Swagger UI can be..."

Copy link
Collaborator Author

Choose a reason for hiding this comment

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

don't think it helps readability as the topic is enabling the Swagger UI

Copy link
Contributor

Choose a reason for hiding this comment

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

that's fair; my concern is that someone will gloss over the importance of "running Entando instance" if they're not familiar with this, like that's an important detail. it should be obvious but i could see myself trying to follow the tutorial locally or with my vm stopped if i didn't have experience or know to ask questions


3. Wait for the application to start.
1. (Optional) Scale the deployment `spec.replicas` to 0.

[INFO] Started ServerConnector@1355c8be{HTTP/1.1, (http/1.1)}{0.0.0.0:8085}
[INFO] Started @66257ms
[INFO] Started Jetty Server
>This is necessary if you're using an in-memory database as in the default quickstart configuration. This will prevent database errors on immediate restarts when the deployment is changed.

4. Navigate to the Swagger UI in a browser at `/entando-de-app/api/swagger-ui.html`
2. Edit the `entando-de-app` deployment. If you have different names for deployment and namespace, adjust the command below accordingly.

http://localhost:[your port]/entando-de-app/api/swagger-ui.html

>Use the [ent CLI](../getting-started/entando-cli.md) to send commands to Kubernetes from the host machine.
```
kubectl -n entando edit deployment/quickstart-deployment
```

## APIs Overview
3. Find the `env` variables section under `spec.template.spec.containers.env[image: entando-de-app]`

The Entando core exposes REST APIs for every action that can be taken in
the App Builder environment. For example, you can use
these APIs to create pages, create page templates or to add widgets to
pages. The APIs can be used to support automation, testing, or
integrations with external systems.
4. To enable the Swagger UI, add the "SPRING_PROFILES_ACTIVE" variable. If it is already present, add `swagger` to its comma-delimited value list:
```
- name: SPRING_PROFILES_ACTIVE
value: default,swagger
```

### API structure
5. (Optional) Reset the deployment `spec.replicas` back to 1 if it was changed in a previous step. Save the deployment to update.

All of the APIs share a common top level structure. Each response will
contain a top level entry for `errors`, `metadata`, and `payload`.
### Disable Swagger UI

The `errors` will always contain code and a message string indicating an
error condition in the request. The `metadata` section is used for
paging, sorting, filtering and data that is distinct from the body. The
body of each response is included in the `payload` section of the
response and varies according to each API.
Repeat the steps above, but in step 4, remove `swagger` from the value list.

### Models
## Find Your Client Secret
You'll need your client credentials to execute Entando APIs.

All of the model classes returned by the Entando core are annotated so that the model definition is included in the Swagger documentation. At the bottom of the Swagger page all of the model classes returned by the API endpoints can be found.
1. Log in into your Keycloak Administration Console at `http://[YOUR-HOST-NAME]/auth`. To find the Keycloak admin credentials, see the [Entando Identity Management System](./identity-management.md) page.

## Tutorial
2. From the left navigation panel, go to `Clients`

1. Access your application Swagger UI as discussed above
3. Select the desired client (e.g. in a quickstart environment, this is `quickstart`)

2. Click on the `Authorize` button in the upper right corner
4. Click on the `Credentials` tab to retrieve the Secret. Save the `Client Id` and `Secret` for the steps below.

3. Enter the client id and client secret in the open window and click `Authorize`
## Access the APIs on Swagger
1. To see the APIs, go to:
``` sh
http://[YOUR-HOST-NAME]/entando-de-app/api/swagger-ui.html
```

4. If you are redirected to the Entando login page, log in with your credentials (default are `admin`/`adminadmin`)
2. Click on the Authorize button in the upper right corner.
Copy link
Contributor

Choose a reason for hiding this comment

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

notice that there are periods for single-sentence steps here (no periods used for single sentences in above steps)

Copy link
Collaborator Author

Choose a reason for hiding this comment

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

this was the only one without in this list so it looked odd


5. You will be redirected to the Swagger UI page, now authenticated
3. Enter the client ID and Secret from above. Click Authorize.

6. Use the **Try it out** button on the APIs
4. You will be prompted to log in to your Keycloak instance as an Entando admin user if you have not already done so. The default credentials are admin/adminadmin.

- Scroll to `widget-controller`
5. You will be redirected to the authenticated Swagger UI page. Select an API to see the methods in the drop-down list and click the `Try it out` button.
Copy link
Contributor

Choose a reason for hiding this comment

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

its methods (not all methods are the same??)

Copy link
Collaborator Author

Choose a reason for hiding this comment

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

methods are API thing, get post delete etc.

Copy link
Contributor

Choose a reason for hiding this comment

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

no no no, sorry - i mean do the same methods apply to all the APIs or do different APIs support different methods? if the same always apply then "the methods" is the way to go because there is only one set and it's used for every API - the specificity works. but if different APIs have different methods then "the" APIs is imprecise, but "its APIs" is specific

Copy link
Collaborator Author

@jyunmitch jyunmitch Feb 17, 2023 •
edited
Loading

Choose a reason for hiding this comment

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

the way others talk about methods, they don't generally seem to talk about it that way. Each one may have different items and request things in it, but 'get' always works the same way so they talk about methods in a general way. 'its' methods sounds wrong

Copy link
Contributor

Choose a reason for hiding this comment

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

not sure what the GET method has to do with this? pretty sure most everyone would use "its"
Screen Shot 2023-02-17 at 8 50 08 AM

Copy link
Collaborator Author

@jyunmitch jyunmitch Feb 17, 2023 •
edited
Loading

Choose a reason for hiding this comment

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

methods in Rest APIs are specifically get, post, delete, etc and there's a limited list. It's not talking about methods in general

Copy link
Contributor

Choose a reason for hiding this comment

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

great. that clears it up

Example:
1. Scroll down to `widget-controller` and click anywhere on the row

- Select the blue GET row
2. Select the `GET` method

- Select **Try it out**
3. Click `Try it out`

- Look at the results in the window. You should see a Server response with Code 200 and full response body.
4. See the results in the window below showing Code 200 and a full response body
Loading