hale»connect API documentation #71

Kate-Lyndegaard · 2023-11-16T11:40:25Z

This PR adds documentation about the hale»connect API and how to use it.

ING-4009

morch23mj

LGTM. Will the German translation be added in this PR as well? If so, it can be done under the same folder tree in i18n/de/docusaurus-plugin-content-docs/current/.

stempler · 2023-11-17T09:52:01Z

docs/references/haleconnect-api/2023-11-15-haleconnect-api.md

+
+Enter this URL in your favorite browser: https://haleconnect.com/swagger/
+
+For on-premise users, enter: https://[yourdomain]/swagger/


Depends on if they have enabled it.

stempler · 2023-11-17T09:54:50Z

docs/references/haleconnect-api/2023-11-15-haleconnect-api.md

+
+  Attachment: https://haleconnect.com/store/attachments/swagger.yaml
+
+A bucket is a container for objects stored in Amazon S3. The hale»connect bucket service APIs provide access to files and datasets associated with each resource type.


Maybe more general referring to "file storage" instead of "Amazon S3"? The internals don't really matter for the API and depending on the setup AWS is not used.

stempler · 2023-11-17T09:56:32Z

docs/references/haleconnect-api/2023-11-15-haleconnect-api.md

+
+The interaction service provides access to comments, tasks and notes on a given resource, as well as the forum.
+
+### Notification service


I would maybe leave this one out. There aren't really any useful endpoints for end users I think.

stempler · 2023-11-17T09:58:13Z

docs/references/haleconnect-api/2023-11-15-haleconnect-api.md

+### Workflow manager
+workflow_manager: https://haleconnect.com/workflows/swagger.yaml
+
+The workflow manager service enables users to access information about ETF Validator and Spatineo monitoring. The generic workflows.....????


The workflow manager is responsible for managing most tasks in the platform like transformations, validation, status updates etc.

morch23mj · 2023-11-17T14:30:42Z

docs/references/haleconnect-api/2023-11-15-haleconnect-api.md

+
+For on-premise users, enter: https://[yourdomain]/swagger/
+
+Select Login, and provide your hale»connect user name and password to obtain an authentication token. Click in the Model Schema field on the right hand side to copy the code template to the body.


Is it guaranteed that they will see the Login endpoint when they open swagger? Otherwise maybe include: if you don't see the login endpoint already, enter in the top bar URL input _https://haleconnect.com/accounts/swagger.yaml_, and click on explore.

morch23mj · 2023-11-17T14:33:07Z

docs/references/haleconnect-api/2023-11-15-haleconnect-api.md

+
+The hale»connect platform can be accessed via API. The hale»connect API enables users to automatically execute workflows, change configuration settings, manage organisations and users, and many other tasks. A series of access URLs permit access to various platform functionality exposed via API. To begin exploring the hale»connect API, it is necessary to log-in using your hale»connect user name and password, in Swagger.
+
+Enter this URL in your favorite browser: https://haleconnect.com/swagger/


Maybe include a general note for the whole document: Throughout the document _https://haleconnect.com_ is used as domain, but replace it with your own custom domain if you have one.

ING-4009

Kate-Lyndegaard · 2023-11-20T09:24:56Z

@stempler @morch23mj I added your feedback.

JohannaOtt

Generally LGTM, I left some comments.
Would it maybe make sense to also quickly introduce the different types of requests (POST, GET,...) that can be made? Not sure if users not used to swagger yet would know where to start/what to do right away even if they know which service is serving for what.

JohannaOtt · 2023-11-20T09:00:12Z

docs/references/haleconnect-api/2023-11-15-haleconnect-api.md

+
+---
+
+The hale»connect platform can be accessed via API. The hale»connect API enables users to automatically execute workflows, change configuration settings, manage organisations and users, and many other tasks. A series of access URLs permit access to various platform functionality exposed via API. To begin exploring the hale»connect API, it is necessary to log-in using your hale»connect user name and password, in Swagger.


A series permit -> a series permits ?

To begin exploring the hale»connect API, it is necessary to log-in using your hale»connect user name and password, in Swagger.
Is it really necessary to use/log in to swagger? We do use many API calls to update resources on the platform etc. without using swagger.

@JohannaOtt
A series of access URLs (plural subject) = permit (plural verb conjugation)

Can you provide a description of other ways you use the hc apis? Or what you would like added here?

That is interesting, thanks for explaining. In German, it would be singular verb conjugation because it is only 1 series.

Can you provide a description of other ways you use the hc apis?

Some examples of using API calls without swagger are for example available in this and this guru card and many more are used in the update tool box we are using in the service team. I assume there are also endpoints available for all of them in swagger (not sure at all though)?

Some examples of using API calls without swagger are for example available in this and this guru card and many more are used in the update tool box we are using in the service team. I assume there are also endpoints available for all of them in swagger (not sure at all though)?

@stempler I have a few questions:

Should curl instructions be added here, or to a separate page about using the hc api with curl?

Are all endpoints listed in the guru cards also available in Swagger?

Does the hc api support any HTTP operations beyond GET, POST, PUT and DELETE? These are the only 4 I can see in Swagger....

Should curl instructions be added here, or to a separate page about using the hc api with curl?

Swagger will show a curl example why trying out a request. Generally I think we should focus on the Swagger/OpenAPI documentation for details and not maintain something else in addition.

Are all endpoints listed in the guru cards also available in Swagger?

Usually yes. There may be some exceptions.
The documentation in the Guru cards probably adds some more information about what the endpoints do any what they are for.

docs/references/haleconnect-api/2023-11-15-haleconnect-api.md

Kate-Lyndegaard · 2023-11-20T09:44:55Z

Generally LGTM, I left some comments. Would it maybe make sense to also quickly introduce the different types of requests (POST, GET,...) that can be made? Not sure if users not used to swagger yet would know where to start/what to do right away even if they know which service is serving for what.

@JohannaOtt I will add a section about the different types of requests.

ING-4009

Kate-Lyndegaard · 2023-11-21T12:15:11Z

@JohannaOtt @stempler I believe I have added all requested changes now, so it would be great if you could give another once over. Once approved, I will go ahead and do the DE translation.

JohannaOtt

I left some minor spelling/wording comments. Overall LGTM

JohannaOtt · 2023-11-22T08:49:39Z

docs/references/haleconnect-api/2023-11-15-haleconnect-api.md

+wetransform can enable use of the hale»connect API for on-premise customers upon request.
+
+
+Select Login, and provide your hale»connect user name and password to obtain an authentication token. If the Login endpoint is not visible, enter https://haleconnect.com/accounts/swagger.yaml in the URL input field at the tope of the page and click on &laquo;Explore&raquo;. Click in the Model Schema field on the right hand side to copy the code template to the body.


at the tope - at the top?

JohannaOtt · 2023-11-22T08:50:18Z

docs/references/haleconnect-api/2023-11-15-haleconnect-api.md

+
+The GET operation requests the retrieval of data.
+
+The POST operation requests that a server accept data contained in the request.


accept - accepts?

JohannaOtt · 2023-11-22T08:50:54Z

docs/references/haleconnect-api/2023-11-15-haleconnect-api.md

+
+The DELETE operation requests deletion of a state or resource.
+
+When working in Swagger, we recommend examining the endpoint, the HTTP operation and the written description of the endpoint available for each entry.


we - wetransform? Not sure if we are usually using first person in the documentation.

ING-4009

Kate-Lyndegaard · 2023-11-22T12:03:37Z

@JohannaOtt OK, great. I added the last changes.

Kate Lyndegaard added 2 commits November 16, 2023 12:28

feat: hc api documentation is added

123aea1

ING-4009

fixup!:typos

fe3bbf8

ING-4009

wetransformer added lang-missing-cs Czech translation is not included in this PR lang-missing-de German translation is not included in this PR help-content Changes to the help content were done help-sidebar Changes to the help sidebar were done labels Nov 16, 2023

Kate-Lyndegaard requested review from JohannaOtt, stempler and morch23mj November 16, 2023 11:40

morch23mj reviewed Nov 16, 2023

View reviewed changes

stempler reviewed Nov 17, 2023

View reviewed changes

morch23mj reviewed Nov 17, 2023

View reviewed changes

fixup!: feedback is added

44b958f

ING-4009

Kate-Lyndegaard requested review from stempler and morch23mj November 20, 2023 09:24

JohannaOtt requested changes Nov 20, 2023

View reviewed changes

morch23mj approved these changes Nov 20, 2023

View reviewed changes

fixup!: additional feedback is added

99370a3

ING-4009

Kate-Lyndegaard requested a review from JohannaOtt November 21, 2023 12:13

JohannaOtt approved these changes Nov 22, 2023

View reviewed changes

fixup!: added last round of feedback

f36c7df

ING-4009

Kate-Lyndegaard merged commit f6282f3 into master Nov 22, 2023
2 checks passed

Kate-Lyndegaard deleted the hc-api branch November 22, 2023 13:22

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

hale»connect API documentation #71

hale»connect API documentation #71

Kate-Lyndegaard commented Nov 16, 2023

morch23mj left a comment

stempler Nov 17, 2023

stempler Nov 17, 2023

stempler Nov 17, 2023

stempler Nov 17, 2023

morch23mj Nov 17, 2023

morch23mj Nov 17, 2023

Kate-Lyndegaard commented Nov 20, 2023

JohannaOtt left a comment

JohannaOtt Nov 20, 2023

JohannaOtt Nov 20, 2023

Kate-Lyndegaard Nov 20, 2023

JohannaOtt Nov 20, 2023

Kate-Lyndegaard Nov 20, 2023

stempler Nov 21, 2023

Kate-Lyndegaard commented Nov 20, 2023

Kate-Lyndegaard commented Nov 21, 2023

JohannaOtt left a comment

JohannaOtt Nov 22, 2023

JohannaOtt Nov 22, 2023

JohannaOtt Nov 22, 2023

Kate-Lyndegaard commented Nov 22, 2023


		Enter this URL in your favorite browser: https://haleconnect.com/swagger/

		For on-premise users, enter: https://[yourdomain]/swagger/


		Attachment: https://haleconnect.com/store/attachments/swagger.yaml

		A bucket is a container for objects stored in Amazon S3. The hale»connect bucket service APIs provide access to files and datasets associated with each resource type.


		The interaction service provides access to comments, tasks and notes on a given resource, as well as the forum.

		### Notification service


		For on-premise users, enter: https://[yourdomain]/swagger/

		Select Login, and provide your hale»connect user name and password to obtain an authentication token. Click in the Model Schema field on the right hand side to copy the code template to the body.


		The hale»connect platform can be accessed via API. The hale»connect API enables users to automatically execute workflows, change configuration settings, manage organisations and users, and many other tasks. A series of access URLs permit access to various platform functionality exposed via API. To begin exploring the hale»connect API, it is necessary to log-in using your hale»connect user name and password, in Swagger.

		Enter this URL in your favorite browser: https://haleconnect.com/swagger/

		wetransform can enable use of the hale»connect API for on-premise customers upon request.


		Select Login, and provide your hale»connect user name and password to obtain an authentication token. If the Login endpoint is not visible, enter https://haleconnect.com/accounts/swagger.yaml in the URL input field at the tope of the page and click on «Explore». Click in the Model Schema field on the right hand side to copy the code template to the body.


		The GET operation requests the retrieval of data.

		The POST operation requests that a server accept data contained in the request.


		The DELETE operation requests deletion of a state or resource.

		When working in Swagger, we recommend examining the endpoint, the HTTP operation and the written description of the endpoint available for each entry.

hale»connect API documentation #71

hale»connect API documentation #71

Conversation

Kate-Lyndegaard commented Nov 16, 2023

morch23mj left a 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

Kate-Lyndegaard commented Nov 20, 2023

JohannaOtt left a 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

Kate-Lyndegaard commented Nov 20, 2023

Kate-Lyndegaard commented Nov 21, 2023

JohannaOtt left a 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

Kate-Lyndegaard commented Nov 22, 2023