API 仕様とフラグメントの設計

Anypoint Code Builder を使用して、新しい API 仕様の作成、設計、テスト、および Exchange へのパブリッシュを行います。

API 仕様を設計するプロセスは、次のとおりです。

ソース管理オプションについては、SCM for API Design Projects (API 設計プロジェクトの SCM) を参照してください。

API 仕様でサポートされる OAS および RAML バージョン

サポートされる OAS および RAML バージョンは、次のとおりです。

OAS 2.0 (JSON)
OAS 2.0 (YAML)
OAS 3.0 (JSON)
OAS 3.0 (YAML)
RAML 1.0
RAML 0.8

サポートされる AsyncAPI バージョンは、次のとおりです。

AsyncAPI 2.6 (JSON)
AsyncAPI 2.6 (YAML)

API フラグメントでサポートされる仕様言語

API フラグメントを API 仕様内に作成するか、含めるか、参照します。

API フラグメントでサポートされる API 仕様言語と構文は、次のとおりです。

OAS 3.0
- YAML
- JSON
RAML 1.0
これらの種別の詳細は、RAML 1.0 仕様を参照してください。
- 特性
- リソース
- ライブラリ
- データ型
- ユーザードキュメント
- 例
JSON スキーマ
Avro 1.9.0 スキーマ

デスクトップ IDE の最小リソース要件

API 仕様を解析するときに、デスクトップ IDE はコンピューターのリソースに依存します。問題を回避するには、コンピューターに次の最小リソースがあることを確認します。

8GB RAM
Ryzen シリーズ 5 / Intel i5 CPU 以上

パーサーの最適なパフォーマンスを実現するには、設計プロジェクト内のすべてのファイルの合計プロジェクトサイズを 500 KB 未満に抑えます。

プロジェクトサイズが 1.5 MB を超えると、検証時間に重大な影響を与えます。

ベストプラクティス

一般的な問題を回避するには、次のガイドラインに従います。

可能な場合は、フラグメントを短い再利用可能な連動関係に分割します。
同じ連動関係の 1 つのバージョンのみを保持します。
一度に 1 つのブラウザータブのみを開いたままにします。

このベストプラクティスは、クラウド IDE にのみ適用されます。
OAS または RAML API 仕様を設計する前に、OAS 仕様のベストプラクティスまたはRAML 仕様のベストプラクティスを確認します。

OAS 仕様のベストプラクティス

$ref プロパティを使用して、再利用可能なコンポーネントを定義します。解析効率を向上させるには、コンポーネント定義を複製する代わりに、API 仕様から各コンポーネントを参照します。次に例を示します。

components:
  schemas:
    User:
      type: object
      properties:
        id:
          type: integer

paths:
  /users:
    get:
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'

可能な場合は、より単純な型を使用してデータを表現します。不要なネストや複雑な型は避けてください。次に例を示します。
```
properties:
  age:
    type: integer  # Prefer simple types over complex types like objects
```
解析効率を向上させるには、値の固定セットを使用する項目の enum プロパティを使用します。
```
properties:
  status:
    type: string
    enum: [active, inactive]
```

オブジェクトに単純なネストを使用して構造を簡略化し、読みやすさと解析効率を改善します。

# Good
properties:
  name:
    type: string
  address:
    type: string

# Avoid
properties:
  user:
    type: object
    properties:
      profile:
        type: object
        properties:
          name:
            type: string

追加情報を提供するには、レスポンスボディの代わりに response ヘッダーを使用します。次に例を示します。

responses:
  '200':
    description: Successful response
    headers:
      X-Rate-Limit-Limit:
        description: The number of requests allowed in the current period
        schema:
          type: integer

簡潔で短い例を指定します。

Book:
  type: string
  example: "Explain the string with as few words as possible."

結合型プロパティを使用する場合、結合型オブジェクト項目を表すには oneOf を使用し、交型の複合オブジェクトと項目を表すには allOf を使用し、複数の考えられるデータ構造でプロパティを定義する場合には anyOf を使用します。

RAML 仕様のベストプラクティス

RAML フラグメントを抽出するときは、最初に各フラグメントをローカル宣言としてインポートします。

フラグメントファイルを作成し、そのフラグメントを Anypoint Exchange にパブリッシュする前に、ローカルフラグメントファイルをインポートして、フラグメントが期待どおりに機能することを検証します。フラグメントが機能する場合は、フラグメントを Exchange にパブリッシュして、フラグメントを複製する代わりに API 仕様で再利用できるようにします。
データ型を宣言として再利用します。

必要な場合にのみ継承を使用します。

Car:
  description: This is a car
  properties:
    brand: string
    model: string
  example:
    brand: Toyota
    model: Corolla
Person:
  properties:
    owns: Car

短い結合を使用します。
```
Person:
  type: Employee | Customer
```

単純な特性を使用し、特性とリソース種別のプロパティを組み合わせないようにします。

/basic:
  type: {resourceTypes.fhirResourceType: {
      postExample : !include /examples/requests/post_resource.json,
      getExample  : !include /examples/responses/get_resource.json,
      bundleName : basic.BasicBundle
    }
  }
  /_search:
    get:
      is: [ searchParams ]
    post:
      is: [ POSTSearchParams ]

API 設計プロジェクトのソース制御

ソース制御管理 (SCM) を使用して、設計、インテグレーション、実装プロジェクトを保存および共有します。 API 設計プロジェクトのソース制御オプションは、プロジェクトの作成方法とタイミングによって異なります。

2024 年 2 月リリース以降、Anypoint Code Builder で [Design an API (API を設計)] (「新しい API 仕様プロジェクトを作成する」を参照) またはコマンド MuleSoft: Design an API を使用して最初から作成した設計プロジェクトでは、MuleSoft VCS を使用して変更を保存および同期しなくなります。
Design Center から Anypoint Code Builder にインポートされたか、2024 年 2 月リリースより前に Anypoint Code Builder で作成された API 設計プロジェクトは、MuleSoft VCS に自動的に接続され、対応する設計プロジェクトと同期できるようになります。

独自のリモートリポジトリを使用する場合は、GitHub を使用することもできます。MuleSoft VCS のプロジェクトと同期せずに API プロジェクトを GitHub のリポジトリに保存するには、「プロジェクトファイルを別のリポジトリにパブリッシュする」を参照してください。

ソース制御オプションについては、ソースファイルの制御を参照してください。