# REST

#### A. REST

REST API 맵핑에는 `subscribe`를 제외한 `call`, `publish`, `map` 커넥터를 이용 할 수 있습니다.

```javascript
    REST: {
      basePath: "/players",
      description: "player service REST API",
      routes: [
```

`basePath`를 기반으로 이하 REST 엔드포인트가 생성됩니다.

`description`은 문서 생성시 활용되며 Markdown을 지원합니다 (옵션).

**Call**

```javascript
        {
          method: "GET",
          path: "/:id",
          deprecated: false,
          description: "Get player information by id",
          call: {
            action: "player.get",
            params: {
              id: "@path.id",
            },          
          },
        },
```

`GET /players/1` 요청이 `player.get` 액션을 `{ id: 1 }` 페이로드와 함께 호출하고 성공시 그 결과를 반환합니다.

`depreacted`는 문서 생성시 활용됩니다 (옵션).

라우트 path를 구성하는 규칙은 [path-to-regexp](https://github.com/pillarjs/path-to-regexp#parameters)를 참고 할 수 있습니다.

```javascript
        {
          method: "GET",
          path: "/me",
          deprecated: false,
          description: "Get player information of mine",
          call: {
            action: "player.get",
            params: {
              id: "@context.user.player.id",
            },          
          },
        },
```

`GET /players/me` 요청이 `player.get` 액션을 `{ id: <인증 컨텍스트의 player.id> }` 정보로부터 페이로드와 함께 호출하고 성공시 그 결과를 반환합니다.

**Map**

```javascript
        {
          method: "GET",
          path: "/me",
          deprecated: false,
          description: "Get player information of mine",
          map: `({ path, query, body, context }) => context.user.player`,
        },
```

또는 `map` 커넥터 (Inline JavaScript Function String)를 통해 인증 컨텍스트의 `player` 객체를 바로 반환 할 수 있습니다. 이후에 다시 다루는 Inline JavaScript Function String은 API Gateway의 Node.js VM 샌드박스에서 해석됩니다.

**Publish**

```javascript
        {
          method: "POST",
          path: "/message",
          deprecated: false,
          description: "Push notifications to all players",
          publish: {
            event: "player.message",
            broadcast: false,
            params: {
              userId: "@context.user.player.id",
              message: "@body.message",
            },
          },
        },
```

`POST /players/1` (body: `{ message: "blabla" }`) 요청은 `player.message` 이벤트를 `{ userId: id: <인증 컨텍스트의 player.id>, message: "blabla" }` 페이로드와 함께 `publish`하고 성공시 발송된 페이로드를 응답합니다.

```javascript
      ],
    },
```

**Params**

REST API의 `params` 맵핑에는 `@path`, `@body`, `@query`, `@context` 객체를 이용 할 수 있습니다.

```javascript
// @body 객체 전체를 페이로드로 전달하거나 스트림을 전달 할 때 이용됩니다.
params: "@body",

// @ 문자열로 시작되지 않는 값들은 해석되지 않고 그대로 전달됩니다.
params: {
  foo: "@path.foo", // will bar parsed
  bar: "query.bar", // will be "query.bar"
  zzz: ["any", { obj: "ject", can: "be", "use": 2 }],
},

// 항상 string 타입을 갖는 @query, @path 객체의 속성들에 한해서 타입을 boolean이나 number로 변환 할 수 있습니다.
params: {
  foo: "@path.foo:number",
  bar: "@query.bar:boolean",
},
```

####


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://moleculer-api.gitbook.io/api/api-schema/protocol/rest.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.