ENDOC-494 update core api tutorial #532

jyunmitch · 2022-07-06T16:17:45Z

No description provided.

nshaw · 2022-07-06T17:45:46Z

vuepress/docs/v7.0/tutorials/devops/invoking-api.md

-Entando supports Swagger and it is accessible, if activated, from its
-web interface from the base application URL at /api/swagger-ui.html. A
-complete list of all available core APIs can be obtained from Swagger.
+Entando Core APIs can be called directly with Swagger or tools like curl and Postman. Entando uses Swagger to automatically generate OpenAPI documentation that allow such interactions. This tutorial describes how to set up an environment ready to invoke the APIs using Postman.


Simplify per today's meeting notes.

nshaw · 2022-07-06T18:01:20Z

vuepress/docs/v7.0/tutorials/devops/invoking-api.md

-(Refer to [User Management Roles](../../docs/consume/identity-management.md#authorization) for details)
+* Basic knowledge of Postman. You can download the Postman Application or use Postman on the web. If you are using the latter, you will need to change the Keycloak configuration.
+* A running Entando instance
+* A running Jhipster application 


For the Core APIs tutorial, this requires a local running copy of the Entando App Engine. See https://github.com/entando/entando-de-app

I couldn't resist trying this live (enable the Swagger UI in an existing entando-de-app deployment. For Wildfly, add _JAVA_OPTION=-Dspring.profiles.active=swagger.) but it didn't work...

JHipster isn't required for the core APIs

watched Anthony on the Oauth2 set up and got confused

vuepress/docs/v7.0/tutorials/devops/invoking-api.md

Lyd1aCla1r3 · 2022-07-06T18:43:05Z

vuepress/docs/v7.0/tutorials/devops/invoking-api.md

-localhost:8080/entando-de-app/api/pages), or the Page Template Controller
-will available under /pageModels (i.e.
-localhost:8080/entando-de-app/api/pageModels) and so on.
+To perform extensive testing with APIs on Postman, set up an environment and define a variable to host the access token saved with a POST request to /oauth/token. This should provide access to all API endpoints and actions for the user's defined privileges. 


"set up an environment" seems a like a given and is a bit awkward to include, especially in such a long sentence that's packed with details. "...Postman, define an environment variable to host the access token saved by issuing a POST request..."
i'd change "with" to "by issuing" because "saved with" reads like something else is saved along with the access token

"for the user's defined privileges" is a little wordy and stands out because it's like intentionally avoiding a reference to authorization
"this should provide access to all API endpoints and actions for which the user is authorized" or something similar?

creating an environment is a literal thing in Postman. You create and send Post requests, and the saving process is done through the variable so it can't be saved by just issuing a post request.

Lyd1aCla1r3 · 2022-07-06T18:48:51Z

vuepress/docs/v7.0/tutorials/devops/invoking-api.md


-(Refer to [User Management Roles](../../docs/consume/identity-management.md#authorization) for details)
+* Basic knowledge of Postman. You can download the Postman Application or use Postman on the web. If you are using the latter, you will need to change the Keycloak configuration.


why is "Application" capitalized?

"using the latter" references "use Postman" which one too many "uses." can simplify to "the latter requires changes to the Keycloak configuration"?

Lyd1aCla1r3 · 2022-07-06T18:50:38Z

vuepress/docs/v7.0/tutorials/devops/invoking-api.md

-## Requirements
+     * `Auth` section
+         1. `Type` → Basic Auth\
+         2. Enter `Username` and `password`. Valid Entando credentials are required. It will be the same as used in the App Builder. 


they will be the same

for the App Builder - credentials are used to access the App Builder, not to access anything within it

Lyd1aCla1r3 · 2022-07-06T18:51:10Z

vuepress/docs/v7.0/tutorials/devops/invoking-api.md

+         2. Enter `Username` and `password`. Valid Entando credentials are required. It will be the same as used in the App Builder. 
+
+     * `Headers` section \
+         Create a new `KEY`: `VALUE` pair as shown: \


wrt the pair, either add space before : or remove space after :

that bothered me so I looked it up, it's used as key-value pair. But here it is written in all caps in Postman so kept it.

Lyd1aCla1r3 · 2022-07-06T19:01:05Z

vuepress/docs/v7.0/tutorials/devops/invoking-api.md


-Create a new Postman environment and define the following variables:
+>If you go to edit the Postman environment you created, you should see that the access_token and the refresh_token variables values have been updated.


variable values

Lyd1aCla1r3 · 2022-07-06T19:01:46Z

vuepress/docs/v7.0/tutorials/devops/invoking-api.md

-### 2. Get an access token
+     * `Headers` section:
+         * Create the key Authorization with Value: Bearer
+         * Create the key Content-Type with Value: application/json`


only one backtick??

why is "Value" capitalized? and why are colons needed?

redid this section. there's column key & column value.
under KEY you enter "Authorization" and for that, under VALUE you enter Bearer<< KEY-VALUE pair. So you create both key and value

Lyd1aCla1r3 · 2022-07-06T19:03:35Z

vuepress/docs/v7.0/tutorials/devops/invoking-api.md

+         * Create the key Authorization with Value: Bearer
+         * Create the key Content-Type with Value: application/json`
+
+2. Select the appropriate method (GET, DELETE, POST etc.) for your request and enter the URL with appropriate values, (i.e. localhost:8080/entando-de-app/api/pages). 


POST, etc.

"desired URL"... "URL with appropriate values" is very odd phrasing

as was, i think because it could be anything IRL

vuepress/docs/v7.0/tutorials/devops/invoking-api.md

Lyd1aCla1r3 · 2022-07-06T19:15:21Z

vuepress/docs/v7.0/tutorials/devops/invoking-api.md


-Getting an access token is a prerequisite to be able to invoke any API.
-The following is the required activity.
+* For more information on testing, the [Collection Runner on Postman](https://learning.postman.com/docs/running-collections/intro-to-collection-runs/) enables you to run the API requests in a collection in a specified sequence. 


this sentence seems incongruous. i'm expecting a link to documentation/resources that discuss testing, not the link to a specific use case. why not "see the Collection Runner on Postman to run the API requests in a collection in a specified sequence"??

The collection runner is a test or a way to run a collection of tests. I think devs would know what is meant here. Running the API request collection in a certain order is like a full batch test of different circumstances I think.

Lyd1aCla1r3 · 2022-07-07T00:10:50Z

vuepress/docs/v7.0/tutorials/devops/invoking-api.md

@@ -15,7 +15,7 @@ To perform extensive testing with APIs on Postman, set up an environment and def
 ## Prerequisites

 * Basic knowledge of Postman. You can download the Postman application or use Postman on the web. The latter requires changes to the Keycloak configuration.
-* A local running copy of the Entando App Engine. For more details, refer to the [Entando App Engine Repository Readme](https://github.com/entando/entando-de-app/blob/develop/README.md#using-swagger)  
+* A local running copy of the Entando App Engine. For more details, refer to the [Entando App Engine GitHub Readme](https://github.com/entando/entando-de-app/blob/develop/README.md#using-swagger)  


add period?

vuepress/docs/v7.0/tutorials/devops/invoking-api.md

nshaw · 2022-07-08T20:26:50Z

@Lyd1aCla1r3 I think we still need this added to /next. Would you be able to handle that?

ENDOC-494 update core api tutorial

fce380b

jyunmitch requested review from nshaw and Lyd1aCla1r3 July 6, 2022 16:17

nshaw suggested changes Jul 6, 2022

View reviewed changes

Lyd1aCla1r3 reviewed Jul 6, 2022

View reviewed changes

jyunmitch added 2 commits July 6, 2022 16:29

ENDOC-494 review edits

5403f77

ENDOC-494 minor edit

9ca5e38

Lyd1aCla1r3 reviewed Jul 7, 2022

View reviewed changes

ENDOC-494 Final edits

5d42ef7

Lyd1aCla1r3 self-requested a review July 8, 2022 19:17

Lyd1aCla1r3 approved these changes Jul 8, 2022

View reviewed changes

nshaw approved these changes Jul 8, 2022

View reviewed changes

ENDOC-494 Apply to Next

2edac28

nshaw merged commit 8ac47ab into main Jul 10, 2022

nshaw deleted the ENDOC-494 branch July 10, 2022 18:03

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

ENDOC-494 update core api tutorial #532

ENDOC-494 update core api tutorial #532

jyunmitch commented Jul 6, 2022

nshaw Jul 6, 2022

nshaw Jul 6, 2022

nshaw Jul 6, 2022

jyunmitch Jul 6, 2022

Lyd1aCla1r3 Jul 6, 2022

Lyd1aCla1r3 Jul 6, 2022

jyunmitch Jul 6, 2022

Lyd1aCla1r3 Jul 6, 2022

Lyd1aCla1r3 Jul 6, 2022

Lyd1aCla1r3 Jul 6, 2022

jyunmitch Jul 6, 2022

Lyd1aCla1r3 Jul 6, 2022

Lyd1aCla1r3 Jul 6, 2022

Lyd1aCla1r3 Jul 6, 2022

jyunmitch Jul 6, 2022

Lyd1aCla1r3 Jul 6, 2022 •

edited

Loading

jyunmitch Jul 6, 2022

Lyd1aCla1r3 Jul 6, 2022

jyunmitch Jul 6, 2022

Lyd1aCla1r3 Jul 7, 2022

nshaw commented Jul 8, 2022


		(Refer to [User Management Roles](../../docs/consume/identity-management.md#authorization) for details)
		* Basic knowledge of Postman. You can download the Postman Application or use Postman on the web. If you are using the latter, you will need to change the Keycloak configuration.


		Create a new Postman environment and define the following variables:
		>If you go to edit the Postman environment you created, you should see that the access_token and the refresh_token variables values have been updated.

ENDOC-494 update core api tutorial #532

ENDOC-494 update core api tutorial #532

Conversation

jyunmitch commented Jul 6, 2022

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Lyd1aCla1r3 Jul 6, 2022 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

nshaw commented Jul 8, 2022

Lyd1aCla1r3 Jul 6, 2022 •

edited

Loading