# 基本概念

組織によるアクセス範囲、リクエストとレスポンスの形式、日時、添付ファイル、未対応の機能。

Source: https://support.toolingmetrics.com/ja/api/concepts/
Updated: 2026-10-28

<a id="base-url"></a>

## ベースURL

APIはメインアプリのパスではなく、専用のサブドメインで提供されます。

```
https://api.toolingmetrics.com/v1
```

リクエストとレスポンスはすべてJSONを使います。書き込みリクエストでは`Content-Type: application/json`を設定してください。

<a id="organization-scoping"></a>

## 組織によるアクセス範囲

Tooling Metricsの各リソースは組織に属します。ほとんどのエンドポイントは`organization_id`のパス要素を必要とします。

```
GET /v1/organizations/:organization_id/machines
GET /v1/organizations/:organization_id/parts
```

`GET /v1/organizations`で組織IDを取得します。存在しない`organization_id`には、トークンが届かない組織と同じ本文で`401 Unauthorized`を返すため、APIからどの組織IDが存在するかを知ることはできません。レコードはURLで指定した組織の中だけで検索します。別の組織のレコードは、そのレコードの組織のIDではトークンで読み取れる場合でも、存在しないIDと同じ本文で`404 Not Found`になります。

所属する有効な`organization_id`を指定するだけでは不十分です。リソースごとの権限が表示範囲をさらに制限します。[認証](https://support.toolingmetrics.com/ja/api/authentication/)の「権限によるアクセス範囲」を参照してください。

<a id="authentication"></a>

## 認証

すべてのリクエストは、`Authorization`ヘッダーにBearerトークンを必要とします。

```
Authorization: Bearer <your-token>
```

トークンは個人用です。組織の管理画面ではなく、アカウント設定（アバター → **設定**）の**APIトークン**タブで作成・取消しを行います。作成者と同じアクセス権を持ちます。[認証](https://support.toolingmetrics.com/ja/api/authentication/)を参照してください。

<a id="no-pagination"></a>

## ページ分割なし

一覧エンドポイント（`index`、`search`）は**ページ分割しません**。一致するすべてのレコードを1つのレスポンスで返し、`page`や`per_page`はありません。件数が多い組織では、本文が大きくなることを考慮してください。ページ分割ではなく、各[リファレンス](https://support.toolingmetrics.com/ja/api/reference/)で説明する検索パラメータで絞り込みます。

一覧レスポンスは、ラッパーのないJSON配列です。

```json
[
  { "id": 1, "...": "..." },
  { "id": 2, "...": "..." }
]
```

例外は`Organizations#show`で、配列ではなく組織名とIDを対応付けるJSONオブジェクトを返します。

<a id="list-vs-detail"></a>

## 一覧と詳細

リソースによっては、次の2つの表現があります。

- **一覧**（`GET /resources`）— プロジェクトは簡潔な概要。機械、加工部品、工具アセンブリは詳細と同じネスト構造。
- **詳細**（`GET /resources/:id`）— 関連データを含む完全なオブジェクト。

例えば`GET /projects`は`{id, name, status, locked}`の概要を返し、`GET /projects/8`はジョブと工程を含む完全なプロジェクトを返します。機械と加工部品は、`index`と`show`で同じ完全な形式を返します。

<a id="read-only-resources"></a>

## 読取り専用リソース

工具アセンブリの作成・編集はTooling Metricsの画面で行います。APIでは**読取り専用**で、`POST`、`PATCH`、`DELETE`のルートはありません。このパスへ書込みメソッドを送ると、ルートに一致せず、定型のJSONエラーではなくルーティング層の失敗になります。文書化したステータスが返るとは限りません。`GET`のみを使用してください。

<a id="date-and-time-format"></a>

## 日時形式

タイムスタンプはすべて、UTCの**ISO 8601**文字列で返します。

```json
"created_at": "2026-06-02T08:30:00Z"
```

書込みリクエストでも同じ形式を使います。

<a id="file-attachments"></a>

## 添付ファイル

画像、図面、STEPモデルは、multipartではなくJSON本文内の**Base64エンコード文字列**で送信します。

```json
{
  "number": "P-0042",
  "model": "<base64-encoded-step-content>"
}
```

項目名と例は[加工部品](https://support.toolingmetrics.com/ja/api/reference/parts/)のリファレンスを参照してください。

<a id="rate-limits"></a>

## レート制限

1トークンにつき毎分60リクエストです。`X-RateLimit-*`ヘッダーはありません。制限関連のヘッダーは、`429`時の`Retry-After`だけです。[レート制限](https://support.toolingmetrics.com/ja/api/rate-limits/)を参照してください。

<a id="common-integrations"></a>

## よくある連携

| 連携 | 内容 | 開始ページ |
|---|---|---|
| CAMソフトウェア | 工具アセンブリと切削データを読み取り、プログラミング後にプロジェクトを送信 | CAM連携ガイド（未公開）。利用できるエンドポイントは[リファレンス](https://support.toolingmetrics.com/ja/api/reference/)を参照。 |
| ERP / MRP | 在庫品目と購入注文を同期する構想。これらのエンドポイントは未実装 | ERP同期ガイド（未公開）。現時点のAPI対応範囲は[未対応の機能](#not-yet-available)を参照。 |
| 工具プリセッタ | 測定したオフセットを書き戻す構想。セット工具への書き込みエンドポイントは未実装 | 生産の自動化ガイド（未公開）。現時点のAPI対応範囲は[未対応の機能](#not-yet-available)を参照。 |
| 独自の自動処理 | 出庫リストの作成や工具収納部の監視の構想。出庫リストの作成エンドポイントは未実装 | 生産の自動化ガイド（未公開）。現時点のAPI対応範囲は[未対応の機能](#not-yet-available)を参照。 |

<a id="not-yet-available"></a>

## 未対応の機能

APIは組織、機械、工具アセンブリ、加工部品、プロジェクトに対応しています。在庫品目、実物の工具の状態・場所、出庫リスト、購入注文はまだ公開しておらず、画面のみで利用できます。在庫水準や購買データを取得するAPIは現時点ではありません。連携ガイドは未公開です。利用できる範囲は[リファレンス](https://support.toolingmetrics.com/ja/api/reference/)を参照してください。