Skip to content

Commit bbc8769

Browse files
Add service request handlers (mendix#12195)
* Add service request handlers * Proofread * Copy changes to Mendix 10 documentation * Proofread --------- Co-authored-by: MarkvanMents <mark.van.ments@mendix.com>
1 parent 19a07c9 commit bbc8769

5 files changed

Lines changed: 63 additions & 9 deletions

File tree

‎content/en/docs/deployment/mendix-cloud-deploy/access-restrictions.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -115,7 +115,7 @@ To apply access restrictions to a specific application environment, follow these
115115

116116
{{% /alert %}}
117117

118-
#### Default Settings
118+
#### Default Settings {#defaults}
119119

120120
These are the default settings:
121121

‎content/en/docs/refguide/runtime/_index.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -76,7 +76,7 @@ You need a license to run an application in production mode. Without a license,
7676
You can extend the functionality of the Runtime Server by writing Java actions. For more information, see the [Mendix Runtime API](/apidocs-mxsdk/apidocs/runtime-api-11/).
7777

7878
{{% alert color="info" %}}
79-
If the app contains published services, links to available API documentation such as [OpenAPI documentation](/refguide/open-api/) for [published REST services](/refguide/published-rest-services/), links to [published OData/GraphQL services](/refguide/published-odata-services/), and WSDLs for [published web services](/refguide/published-web-services/), are available on the URL path `/api-doc` (for example: `https://myapp.mendixcloud.com/api-doc/`).
79+
If the app contains published services, links to available API documentation such as [OpenAPI documentation](/refguide/open-api/) for [published REST services](/refguide/published-rest-services/), links to [published OData/GraphQL services](/refguide/published-odata-services/), and WSDLs for [published web services](/refguide/published-web-services/), are available on the URL path `/api-doc` (for example: `https://myapp.mendixcloud.com/api-doc/`). For more information, see [Service Endpoints](/refguide/request-handlers/#service-endpoints) in *Request Handlers*.
8080
{{% /alert %}}
8181

8282
## Documents in This Category

‎content/en/docs/refguide/runtime/request-handlers.md‎

Lines changed: 30 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -7,9 +7,9 @@ weight: 45
77

88
## Introduction
99

10-
Communication between the Mendix client and the runtime server happens through various different request handlers.
10+
The Mendix Runtime receives requests through various request handlers. [Standard request handlers](#standard-handlers) handle the communication between the Mendix client and the runtime server. [Service endpoints](#service-endpoints) expose the services that your app publishes. You can also create [custom request handlers](#custom-handlers) for your own purposes.
1111

12-
## Standard Request Handlers
12+
## Standard Request Handlers {#standard-handlers}
1313

1414
The following standard request handlers are used:
1515

@@ -33,6 +33,33 @@ The following standard request handlers are used:
3333
The admin port `root` (`/`) URL is not exposed to clients. It uses a different port from the standard request handlers and is only accessible to system administrators.
3434
{{% /alert %}}
3535

36-
## Custom Request Handlers
36+
## Service Endpoints {#service-endpoints}
37+
38+
Apps that contain published services expose endpoints for handling service requests and for documentation.
39+
40+
### Published Service Request Handlers {#published-service-handlers}
41+
42+
[Published REST services](/refguide/published-rest-services/) and [published OData services](/refguide/published-odata-services/) register their own request handlers, based on the location that you configure for each service. For example, a published REST service with the location `rest/myservice/v1` is served on `/rest/myservice/v1`.
43+
44+
If the app contains published web services, the `/ws` request handler handles the web service requests.
45+
46+
### Documentation Endpoints {#documentation-endpoints}
47+
48+
The following endpoints provide documentation for the services published by your app:
49+
50+
| Endpoint | Enabled When | Description |
51+
| -------- | ------------ | ----------- |
52+
| `/api-doc` | The app contains a published REST, OData, or web service. | Overview page that links to the other documentation endpoints. See [Mendix Runtime](/refguide/runtime/#apis). |
53+
| `/rest-doc` | The app contains a [published REST service](/refguide/published-rest-services/). | Serves the [OpenAPI documentation](/refguide/open-api/) of all published REST services. |
54+
| `/odata-doc` | The app contains a [published OData service](/refguide/published-odata-services/). | Serves the API documentation of all published OData services. See [API Documentation](/refguide/published-odata-services/#api-documentation). |
55+
| `/ws-doc` | The app contains a [published web service](/refguide/published-web-services/). | Serves the documentation of all published web services, including its WSDL. |
56+
57+
#### Restricting Access to Documentation Endpoints {#restricting-access}
58+
59+
The Mendix runtime has no setting to disable documentation endpoints. Mendix Cloud denies access to the documentation endpoints by default (see [Default Settings](/developerportal/deploy/access-restrictions/#defaults) in *Restrict Access for Incoming Requests*). On other deployment platforms, you can restrict access to these paths with a reverse proxy or a web application firewall (WAF).
60+
61+
For more information, see [Path-Based Access Restrictions](/developerportal/deploy/environments-details/#path-based-restrictions) in *Environment Details* and [Applying Access Restrictions to Unnecessary Request Handlers](/howto/security/best-practices-security/#request-handlers) in *Implement Best Practices for App Security*.
62+
63+
## Custom Request Handlers {#custom-handlers}
3764

3865
Custom request handlers can be added using the `com.mendix.core.Core#addRequestHandler({name of the request handler})` API call.

‎content/en/docs/refguide10/runtime/_index.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -76,7 +76,7 @@ You need a license to run an application in production mode. Without a license,
7676
You can extend the functionality of the Runtime Server by writing Java actions. For more information, see the [Mendix Runtime API](/apidocs-mxsdk/apidocs/runtime-api-10/).
7777

7878
{{% alert color="info" %}}
79-
If the app contains published services, links to available API documentation such as [OpenAPI documentation](/refguide10/open-api/) for [published REST services](/refguide10/published-rest-services/), links to [published OData/GraphQL services](/refguide10/published-odata-services/), and WSDLs for [published web services](/refguide10/published-web-services/), are available on the URL path `/api-doc` (for example: `https://myapp.mendixcloud.com/api-doc/`).
79+
If the app contains published services, links to available API documentation such as [OpenAPI documentation](/refguide10/open-api/) for [published REST services](/refguide10/published-rest-services/), links to [published OData/GraphQL services](/refguide10/published-odata-services/), and WSDLs for [published web services](/refguide10/published-web-services/), are available on the URL path `/api-doc` (for example: `https://myapp.mendixcloud.com/api-doc/`). For more information, see [Service Endpoints](/refguide10/request-handlers/#service-endpoints) in *Request Handlers*.
8080
{{% /alert %}}
8181

8282
## Documents in This Category

‎content/en/docs/refguide10/runtime/request-handlers.md‎

Lines changed: 30 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -7,9 +7,9 @@ weight: 45
77

88
## Introduction
99

10-
Communication between the Mendix client and the runtime server happens through various different request handlers.
10+
The Mendix Runtime receives requests through various request handlers. [Standard request handlers](#standard-handlers) handle the communication between the Mendix client and the runtime server. [Service endpoints](#service-endpoints) expose the services that your app publishes. You can also create [custom request handlers](#custom-handlers) for your own purposes.
1111

12-
## Standard Request Handlers
12+
## Standard Request Handlers {#standard-handlers}
1313

1414
The following standard request handlers are used:
1515

@@ -22,6 +22,33 @@ The following standard request handlers are used:
2222
| PWA Manifest | `/manifest.webmanifest` | Serves the manifest file that is required for [PWA applications](/refguide10/mobile/introduction-to-mobile-technologies/progressive-web-app/). |
2323
| Mx Dev Tools | `/mxdevtools` | Websocket endpoint that handles client logs and nanoflow debugging. Only enabled during development. |
2424

25-
## Custom Request Handlers
25+
## Service Endpoints {#service-endpoints}
26+
27+
Apps that contain published services expose endpoints for handling service requests and for documentation.
28+
29+
### Published Service Request Handlers {#published-service-handlers}
30+
31+
[Published REST services](/refguide10/published-rest-services/) and [published OData services](/refguide10/published-odata-services/) register their own request handlers, based on the location that you configure for each service. For example, a published REST service with the location `rest/myservice/v1` is served on `/rest/myservice/v1`.
32+
33+
If the app contains published web services, the `/ws` request handler handles the web service requests.
34+
35+
### Documentation Endpoints {#documentation-endpoints}
36+
37+
The following endpoints provide documentation for the services published by your app:
38+
39+
| Endpoint | Enabled When | Description |
40+
| -------- | ------------ | ----------- |
41+
| `/api-doc` | The app contains a published REST, OData, or web service. | Overview page that links to the other documentation endpoints. See [Mendix Runtime](/refguide10/runtime/#apis). |
42+
| `/rest-doc` | The app contains a [published REST service](/refguide10/published-rest-services/). | Serves the [OpenAPI documentation](/refguide10/open-api/) of all published REST services. |
43+
| `/odata-doc` | The app contains a [published OData service](/refguide10/published-odata-services/). | Serves the API documentation of all published OData services. See [API Documentation](/refguide10/published-odata-services/#api-documentation). |
44+
| `/ws-doc` | The app contains a [published web service](/refguide10/published-web-services/). | Serves the documentation of all published web services, including its WSDL. |
45+
46+
#### Restricting Access to Documentation Endpoints {#restricting-access}
47+
48+
The Mendix runtime has no setting to disable documentation endpoints. Mendix Cloud denies access to the documentation endpoints by default (see [Default Settings](/developerportal/deploy/access-restrictions/#defaults) in *Restrict Access for Incoming Requests*). On other deployment platforms, you can restrict access to these paths with a reverse proxy or a web application firewall (WAF).
49+
50+
For more information, see [Path-Based Access Restrictions](/developerportal/deploy/environments-details/#path-based-restrictions) in *Environment Details* and [Applying Access Restrictions to Unnecessary Request Handlers](/howto/security/best-practices-security/#request-handlers) in *Implement Best Practices for App Security*.
51+
52+
## Custom Request Handlers {#custom-handlers}
2653

2754
Custom request handlers can be added using the `com.mendix.core.Core#addRequestHandler({name of the request handler})` API call.

0 commit comments

Comments
 (0)