@TOC
介绍（Introduction）
REST是什么？
REST全称是Representational State Transfer，中文意思是表述（编者注：通常译为表征）性状态转移。 它首次出现在2000年Roy Fielding的博士论文中，Roy Fielding是HTTP规范的主要编写者之一。 他在论文中提到："我这篇文章的写作目的，就是想在符合架构原理的前提下，理解和评估以网络为基础的应用软件的架构设计，得到一个功能强、性能好、适宜通信的架构。REST指的是一组架构约束条件和原则。" 如果一个架构符合REST的约束条件和原则，我们就称它为RESTful架构。
REST本身并没有创造新的技术、组件或服务，而隐藏在RESTful背后的理念就是使用Web的现有特征和能力， 更好地使用现有Web标准中的一些准则和约束。虽然REST本身受Web技术的影响很深， 但是理论上REST架构风格并不是绑定在HTTP上，只不过目前HTTP是唯一与REST相关的实例。 所以我们这里描述的REST也是通过HTTP实现的REST。
Published REST Service
Published REST Service：Mendix Studio Pro中的Published REST Service功能通过REST标准 来暴露你的 Entities(实体) 和 Microflow（微流)给其他应用App 使用。
一般属性
Service Name（服务名称）
Service Name 服务名称是用来识别应用中的服务。它还显示在 OpenAPI (Swagger) documentation page。 当服务最初创建时，服务名称用于创建服务的默认位置。如果服务名称包含任何空格或特殊字符，则它们将被服务位置中的字符“_”替换。
Version (版本)
Version （版本）是用来展示版本信息在 OpenAPI (Swagger) documentation page。你可以设置任何的字符串String在Version 版本中，但是建议符合 semantic versioning scheme。 默认 Version 版本信息设置为“1.0.0”。
Location 位置信息
Location 展示URL在一个Service 服务被访问时。 默认， Location 位置 信息由 Service Name (服务名称)，和"v1"到"rest/"前缀建立起来。 在URL中 Service Name 服务名称中的空格和任何其他的特殊字符都会被剥离成“_”。 示例：
http//localhost:8080/rest/my_service_name/v1
你可以改变默认的Location 位置信息-几乎所有合格的URL。
Reserved Prefixes 保留的前缀
下面展示的URL前缀是不允许被使用在Location信息中的：
ws/
ws-doc/
rest-doc/
odata/
odata-doc/
api-doc/
xas/
p/
reload/
当你的应用在运行的时候，你可以点击这个Location 去打开交互文档页面。
Public Documentation 公共文档
公共文档使用服务文档 OpenAPI 2.0 (Swagger) Documentation,你可以使用对于富文本的版本 GitHub-flavored markdown
导出swagger.json
为了保存一个服务的 OpenAPI (Swagger) documentation page在你的机器上，右键点击这个服务在App Explorer 并且选择Export Swagger.json(或者只点击这个Export Swagger.json 按钮，依赖于你的Studio Pro 的版本)。 这是一个机器可读的文件在OpenAPI 2.0 file format。大部分的API 工具支持这个格式。 当 应用运行时，这个文件 在 /rest-doc/servicename/swagger.json.
Security 安全
需要身份认证
选择客户端是否需要身份认证。
身份认证的方式。
如果需要身份认证，你可以按照你的习惯选择身份认证的方式。
- 选择Username 和Password 的方式让客户端进行身份认证，在Authorization Header中（这种是基础的身份认证的方式）。
- 选择激活Session 会话来自于JavaScript 在你当前应用中。 -- 用户一登录到浏览器，JavaScript在你的App中访问REST Service 使用当前用户的Session。 -- Offline-first应用不能使用激活Session的身份认证，因为他们没有会话激活在应用运行时。 -- 了防止跨站点请求伪造，需要在每个请求上设置标题，例如X-Csrf-Token
var xmlHttp = new XMLHttpRequest();
xmlHttp.open("GET", "http://mysite/rest/myservice/myresource", false);
xmlHttp.setRequestHeader("X-Csrf-Token", mx.session.getConfig("csrftoken"));
xmlHttp.send(null);
- 选择自定义使用微流进行身份验证。每次用户想要访问资源时，此微流都会被调用。 检查多个身份验证方法，让服务尝试其中的每一个。它将首先尝试自定义身份验证，然后尝试用户名和密码，然后进行活动会话。有关详细信息，请参阅已发布的 REST 路由。
微流
指定用于自定义身份验证的微流。
选择参数，查看传递到身份验证微流的参数列表。在该窗口中，您可以指示身份验证微流的参数是来自请求头还是来自查询字符串。
微流可能以Http 请求为参数，以便检查传入请求。
微流也可能以响应响应为参数。当微流将此响应的状态代码设置为其他200时，此值将被返回，并且操作将不会执行。在这种情况下，响应上设置的任何标题也会返回。
身份验证微流应返回用户。
认证微流有三种可能的结果：
- 当 Http 响应参数的状态代码设置为其他200时，则返回此值，并且不会执行操作
- 否则，当生成的用户不是空的时，操作在该用户的上下文中执行
- 否则，当生成的用户为空时，将尝试下一种身份验证方法。如果没有其他身份验证方法，结果为404 未找到。
允许角色
允许的角色定义了用户必须能够访问服务的模块角色。此选项仅在"需要身份验证"设置为"是"时可用。
网络服务用户无法访问 REST 服务。
启用 CORS
当您的服务需要在您自己的网站之外可用时，请选中此框。
单击"设置"按钮以更详细地指定此访问（例如，允许哪些网站访问该服务）。
资源
一个REST Service 暴露 一批资源。在这个资源中你可以定义ET, PUT, POST, PATCH, DELETE, HEAD and OPTIONS操作。 你可以托一个Entity或者信息的定义在列表在[生成一个完整的资源]（https://docs.mendix.com/refguide/generate-rest-resource）。
操作
当你选择了一个资源后，你看到这个操作对于那个你选择的资源。
如何发布一个REST Service
介绍
Mendix Studio pro 允许你发布REST Web Service。 本篇主要介绍如何使用Mendix Studio Pro 发布一个Get 操作的Published REST Service. 主要做的事情是，创建一个Published REST Service和以JSON或者XML的格式返回结果。
前期准备工作
在开始所有操作之前，请确保下载了Mendix Studio Pro。
配置样例 Project
创建一个空的Mendix Project后，你需要操作一下几个步骤：
- 重命名MyFirstModule 为RESTExample。
- 打开RESTExample中的Domain model。
- 创建Entities 按照图中的属性名称设置并给予与图中相同的关联关系。
4. 你需要右键点击OrderItem 或Order Entity选择Generate Overview pages.
5.将Overview Page 关联到Navigation 导航，然后运行项目添加一些数据。
发布REST Service
1.在 App Explorer, 右键点击 RESTExample module 并且选择Add > Other > Message Definitions:
2.在Add Message Definition 对话框中输入MD_Orders 作为 这个的名称定义。
3. 这个消息的定义已经打开了，你需要去选择用于MD_Orders 定义的Entity。为了做这个操作，选择Add 并且在对话框中，点击Select，然后选择Order Entity对于这个List。
4.在选择完Order Entity，这个对话框中的Structure 结构部分填充只有Order 对象被选中。
4. 选择Order ID 和Customer 属性。
5. 展开OrderItem_Order关联并且选择Product和Quantity 属性。
6. 点击OK来关闭对话框。
7. 关闭message definition 并且确保保存定义，如果弹出对话框询问是否保存时。
配置REST Service
1.在App Explorer，右键点击RESTExample Module ，并且选择 Add > Other > Published REST Service
2. 输入PRS_OrderService 为的REST Service的名称。
3. 添加一个新的资源到你的服务通过点击Add，并且输入GetOrderByID 为Resource name:
4.
选择Ok 来关闭对话框。
4. 添加一个operation 操作到你的资源中通过点击Add在Operations for resource 选项中。
5. 在operation 操作对话框，输入**{OrderID}**在Operation Path ，这将允许REST Service被调用通过指定OrderID在URL中在Example location的输入框中。
6. 在相同的对话框，点击Microflow的Select。由于你没有创建过Microflow 微流对于这个操作，选择RESTExample Module 在对话框中然后点击New 来创建一个新的微流。输入PRS_GetGetOrderByID 作为新Microflow微流的名称。
7. 点击show 来开始编辑这个新建的微流。
8. 检查2个参数HttpRequest 和OrderID是否存在，若没有请自行添加。
9. 添加一个Action 对于这个微流来覆盖OrderID 变量（String）为一个Integer 变量。
查询OrderID（autonumber）需要做这个操作。
10. 添加第二个Activity 对于这个微流来获得Order 基于OrderID。这个Retrieve操作只返回1个Order。
11. 在App Explorer，右键点击 RESTExample module并且选择Add other > Export Mapping 来添加一个新的Mapping 映射命名为EM_ExportOrder
12. 在Select schema elements for export mapping对话框中，选择Message definition选项，然后选择之前创建的MD_Orders映射通过Select按钮。
确保选择所有的展示出的属性，点击OK
13. 在Export Mapping ，映射Objects到相同Objects 来自Domain model.双击右边的Order然后选择相对应的Entity。
14. 现在返回 PRS_GetGetOrderByID microflow 微流并且添加一个 Export with mapping 的activity.
15. 在Mapping区域选择在第11步创建的 mapping . 对于 Parameter参数 field, 选择 Order object 对象retrieved获取于 database 通过retrieve action 在 microflow.
16. 选择JSON 作为result结果, 并且存储output 作为一个 String variable变量. 输入 Order_JSON作为variable变量名称.
17添加一个Activity在微流中来创建一个HttpResponse的对象。
StatusCode ： 200
content ：mapped to the exported JSON from step 16.
HttpVersion ： 'HTTP/1.1'.
17. 添加一个Activity在微流中，用来创建请求头。
Key ： 'Content-Type'
Value ： 'application/json'(or 'application/xml' if your response contains XML rather than JSON).
Set the System.HttpHeaders association to your HTTP response.
19. 打开End Activity 在你的微流中选择$NewHttpResponse 作为返回值。
浏览你的应用
- 运行你的App打开你浏览器输入
http://localhost:8080/rest-doc/
-
你会看到图中页面
3.点击 PRS_OrderService查看：
-
点击Get 然后点击try it out
-
填入OrderID点击Execute：
5.执行request返回这个结果在 Response body：
感谢阅读
Mendix官网：https://www.mendix.com/zh/
Mendix行业解决方案：https://solutions.mendix.com/
Mendix平台指南：https://www.mendix.com/evaluation-guide/
Mendix动画展示：https://www.mendix.com/demos/
Mendix公众号：搜索Mendix ————————————————
