---
title: 外部APIデータ連携ガイドライン
description: 外部のAPIとの連携して開発を進める場合、その仕様について明確に定まっていると様々な問題を未然に回避することができます。
---

APIを利用し、ご利用のシステムで管理しているデータとKurocoの連携ができます。  
API連携することで、データを重複で管理することなく、効率的な運用が可能になります。

本ドキュメントでは、連携する外部APIの仕様についておすすめの対応方法を記載します。

## 連携方法
外部のAPIと連携して開発を進める場合、仕様について明確に定まっていると様々な問題を未然に回避できます。
APIの標準化手法としては、**OpenAPI**や**GraphQL**がスタンダードになっています。

これらの仕組みに従うことにより、自然と抜け漏れや認識齟齬の解消ができます。  
また、仕様記述ツールを活用することで、コミニケーションを円滑に進めることも可能です。

## OpenAPIを利用する
OpenAPIの場合、下記いずれかの方法でご対応ください。

### 定義ファイルを作成する
JSON形式、またはYAML形式で記述されたファイルを作成する方法です。

### 外部のAPIにplayground/IDEを公開する  
[Swagger Editor](https://swagger.io/tools/swagger-editor/)を利用し、公開してもらう方法です。  

:::note
公開いただく場合、セキュリティのためBasic認証をつけていただくことをお勧めします。
:::

### HTMLファイルを作成する
OpenAPI仕様記述ツールを利用し、DocumentationGeneratorで生成されたHTMLファイルとして出力する方法です。

## GraphQLを利用する
GraphQLの場合、下記いずれかの方法でご対応ください。

### 定義ファイルを作成する
スキーマ定義言語(`schema.graphqls`)で記述されたファイルを作成する方法です。

### 外部のAPIにplayground/IDEを公開してもらう  
[GraphiQL](https://github.com/graphql/graphiql)を利用し、公開してもらう方法です。  

:::note
公開いただく場合、セキュリティのためBasic認証をつけていただくことをお勧めします。
:::

### HTMLファイルを作成する
GraphQL仕様記述ツールを利用し、DocumentationGeneratorで生成されたHTMLファイルとして出力する方法です。

## 参考
### 仕様記述ツール
API仕様記述ツールの一例を紹介します。
- [Swagger Editor](https://editor.swagger.io/)
- [API doc](https://apidocjs.com/)
- [raml2html](https://github.com/raml2html/raml2html)
- [ReDoc](https://github.com/Redocly/redoc)

### 参考リンク
OpenAPI、GraphQLについての詳細は下記公式サイトをご確認ください。
- [What Is OpenAPI](https://swagger.io/docs/specification/about/)
- [GraphQL](https://graphql.org/)
