みなさん、こんにちは。エンジニア・デザイナー採用担当の平木です。 メドレーでは iOS 開発コミュニティに微力ながら還元したいと、2017 年より iOSDC に協賛をさせていただいておりますが、今年も シルバースポンサー として協賛させていただくことになりました。 過去の参加レポート entry/2018/09/13/175702 entry/2017/09/27/120000 iOSDC 初のオンライン開催 今年の iOSDC は初のオンライン開催ということで、例年とはまた違った楽しみ方ができそうです。 公式スタッフブログに記載されていますが、今年はノベルティグッズが 配送 されるとのことで、既に届いている方もいらっしゃるようです。弊社のパンフレットも同封させていただいてます。 今年の タイムテーブル も大変興味深い内容が多く、今から視聴が楽しみですが(スポンサーチケットを頂いてはいますが、筆者も自腹でチケット購入しています) ニコニコ生放送での視聴 ということで、例年とは違い、コメントなどで盛り上がりがあるのではないかと、大変期待しています。 Ask the Speaker では Discord を使用するということで、対面とはまた違ったコミュニケーションが取れそうです。参考 URL や図などがすぐに出してもらえたりなど、さらに学びが深くなるのではないかと思っています。 最後に 今回は直接会場でみなさんとの交流はできませんが、弊社のエンジニアも参加予定ですので、一緒に楽しんでいきたいと思います。後日イベントレポートもこちらで公開したいと考えています。 また、メドレーではこうしたイベントにも興味をお持ちの iOS エンジニアを絶賛募集中です。お気軽に下記よりご連絡いただければ、カジュアルにお話をしたいです! 募集の一覧 | 株式会社メドレー メドレーの採用情報はこちらからご確認ください。 www.medley.jp

みなさん、こんにちは。エンジニア・デザイナー採用担当の平木です。 メドレーでは iOS 開発コミュニティに微力ながら還元したいと、2017 年より iOSDC に協賛をさせていただいておりますが、今年も シルバースポンサー として協賛させていただくことになりました。 過去の参加レポート entry/2018/09/13/175702 entry/2017/09/27/120000 iOSDC 初のオンライン開催 今年の iOSDC は初のオンライン開催ということで、例年とはまた違った楽しみ方ができそうです。 公式スタッフブログに記載されていますが、今年はノベルティグッズが 配送 されるとのことで、既に届いている方もいらっしゃるようです。弊社のパンフレットも同封させていただいてます。 今年の タイムテーブル も大変興味深い内容が多く、今から視聴が楽しみですが(スポンサーチケットを頂いてはいますが、筆者も自腹でチケット購入しています) ニコニコ生放送での視聴 ということで、例年とは違い、コメントなどで盛り上がりがあるのではないかと、大変期待しています。 Ask the Speaker では Discord を使用するということで、対面とはまた違ったコミュニケーションが取れそうです。参考 URL や図などがすぐに出してもらえたりなど、さらに学びが深くなるのではないかと思っています。 最後に 今回は直接会場でみなさんとの交流はできませんが、弊社のエンジニアも参加予定ですので、一緒に楽しんでいきたいと思います。後日イベントレポートもこちらで公開したいと考えています。 また、メドレーではこうしたイベントにも興味をお持ちの iOS エンジニアを絶賛募集中です。お気軽に下記よりご連絡いただければ、カジュアルにお話をしたいです! 募集の一覧 | 株式会社メドレー メドレーの採用情報はこちらからご確認ください。 www.medley.jp

みなさん、こんにちは。エンジニア・デザイナー採用担当の平木です。 メドレーでは iOS 開発コミュニティに微力ながら還元したいと、2017 年より iOSDC に協賛をさせていただいておりますが、今年も シルバースポンサー として協賛させていただくことになりました。 過去の参加レポート entry/2018/09/13/175702 entry/2017/09/27/120000 iOSDC 初のオンライン開催 今年の iOSDC は初のオンライン開催ということで、例年とはまた違った楽しみ方ができそうです。 公式スタッフブログに記載されていますが、今年はノベルティグッズが 配送 されるとのことで、既に届いている方もいらっしゃるようです。弊社のパンフレットも同封させていただいてます。 今年の タイムテーブル も大変興味深い内容が多く、今から視聴が楽しみですが(スポンサーチケットを頂いてはいますが、筆者も自腹でチケット購入しています) ニコニコ生放送での視聴 ということで、例年とは違い、コメントなどで盛り上がりがあるのではないかと、大変期待しています。 Ask the Speaker では Discord を使用するということで、対面とはまた違ったコミュニケーションが取れそうです。参考 URL や図などがすぐに出してもらえたりなど、さらに学びが深くなるのではないかと思っています。 最後に 今回は直接会場でみなさんとの交流はできませんが、弊社のエンジニアも参加予定ですので、一緒に楽しんでいきたいと思います。後日イベントレポートもこちらで公開したいと考えています。 また、メドレーではこうしたイベントにも興味をお持ちの iOS エンジニアを絶賛募集中です。お気軽に下記よりご連絡いただければ、カジュアルにお話をしたいです! https://www.medley.jp/jobs/

こんにちは、インキュベーション本部エンジニアの加藤です。 主に CLINICS アプリ の開発を担当しています。 はじめに CLINICS アプリの開発では OpenAPI や gRPC を利用しています。 OpenAPI と gRPC の間には何の関係もないのですが、どちらも API の仕様をスキーマ言語で記述するという点では共通しています。 今回はこの API スキーマが開発にもたらすメリットについて紹介していこうと思います。 API ドキュメントとしてのスキーマ定義 既存のコードに機能を追加する際や修正を加える際に気にすることの多い部分は API の仕様ではないかと思います。 「リクエストやレスポンスはどのようなデータなのか」「この値は必須なのか、任意なのか」「データの型は数値なのか、文字列なのか」「フォーマットは決まっているのか」など、多くのことを把握する必要があります。 しかし、こういった API 仕様のドキュメントが整備されていないということも多いのではないでしょうか。 また、ドキュメントはあるけれどリクエストとレスポンスのサンプル JSON が貼ってあるだけだったり、時間が経つうちに実装とドキュメントが乖離してしまいアテにならなくなってしまっている場合もあります。 参考にできるドキュメントがない場合は、直接バックエンドの実装を見に行くこともあるのですが、目的のコードを探し出して読み解くのは意外と時間がかかります。 特に自分以外のエンジニアが実装した機能の場合、API の仕様を実装から紐解くのはかなり骨が折れる作業です。 CLINICS アプリの開発ではこういった手間を減らすために OpenAPI や gRPC を利用しています。 REST API のスキーマは OpenAPI を使って記述しています。 gRPC を利用している部分は Protocol Buffers で RPC のインターフェースが記述されるため、これが API のスキーマになっています。 OpenAPI や Protocol Buffers の定義を参照することで API の仕様が容易に把握できるため、非常に便利です。 OpenAPI や Protocol Buffers などのスキーマ言語の良い点は、宣言的な DSL でスキーマを定義できる点です。 実装言語に依存しない形での記述ができ、自然言語のような曖昧さもないためより正確に API 仕様を記述することができます。 ここからは OpenAPI や Protocol Buffers の実際に記述例を挙げながら、どういった形でスキーマを記述していくのか簡単に見ていきたいと思います。 OpenAPI OpenAPI は REST API のインターフェースを記述する仕様です。 エンドポイントのリクエストパラメータやレスポンスの構造などを JSON や YAML で記述していくことができます。 かつては Swagger という名称だったため、そちらの名前で知っているという方もいらっしゃるかもしれません。 実際の OpenAPI の定義は以下のような形になります。 openapi : 3.0.2 info : { title : OpenAPI Sample , version : 1.0.0 } paths : "/users/{user_id}" : get : parameters : - name : user_id in : path required : true schema : { type : string } responses : "200" : description : OK content : application/json : schema : type : object properties : id : { type : string } name : { type : string } age : { type : integer , nullable : true } required : [ id , name , age ] "404" : description : Not Found "500" : description : Internal Server Error 例としてユーザー ID からユーザーのデータを取得する API を記述してみました。 上記の定義を見ると、 GET: /users/{user_id} というエンドポイントがある ユーザーの ID ( user_id ) を string でパラメータとしてパスの中に埋め込む レスポンスは 200, 404, 500 が返ってくる可能性がある といったことが読み取れるかと思います。 また、レスポンスは以下のような JSON が返ってくることもスキーマから読み取ることができます。 { "id" : "12345678-1234-1234-1234-123456789abc" , "name" : "user name" , "age" : 25 } ここでは OpenAPI の記述の仕方についてあまり深く触れませんが、この他にもデータのフォーマットや省略された場合のデフォルト値などの記述なども可能です。 より詳しくは こちら を参考にしてみてください。 これらをうまく使うことでより正確に API の仕様を記述することができます。 Protocol Buffers Protocol Buffers は主に gRPC で用いられるデータのシリアライゼーション形式です。 専用のスキーマ言語を用いてデータの構造や RPC のメソッドの定義を .proto ファイルに記述していきます。 実際の .proto ファイルは以下のような形になります。 syntax = "proto3" ; package example.protobuf ; service UserService { rpc GetUser ( GetUserRequest ) returns ( GetUserResponse ); } message GetUserRequest { string id = 1 ; } message GetUserResponse { User user = 1 ; } message User { string id = 1 ; string name = 2 ; int32 age = 3 ; } 少し独特な見た目をしていますが、 message として構造体のようなデータ構造が定義されていることが見て取れると思います。 各メッセージにはフィールドが定義されており、型とフィールド名が宣言されています。 スキーマ言語を使うメリット スキーマはドキュメントの代わりとして使えるだけでなく、他にもいくつか使い道があるので紹介していこうと思います。 スキーマからソースコードを自動生成できる スキーマ言語による記述は人間にとって読みやすいだけでなく機械的に処理できる形式でもあるので、スキーマからソースコードを自動生成することも可能です。 プログラミング言語や使っているフレームワークによらず、サーバー側ではリクエストのバリデーションを、またクライアント側ではレスポンスの JSON をクラスや構造体に詰めるような処理を書くことが多いのではないでしょうか。 事前にスキーマ定義を書いている場合はスキーマを見ながらこういったコードを書き起こしていくことになるのですが、せっかく machine-readable な形のスキーマがあるのだから自動でコードを生成したくなるのが自然な考えでしょう。 自動で生成してしまえば定型のコードを書く手間を減らせるだけでなく、手書きするとどうしても起こしがちな JSON のキー名を間違えるといったミスを防ぐこともできます。 また、Web, iOS, Android などの複数プラットフォームでサービスを展開している場合でも、それぞれの実装が乖離しないように管理していくことも容易です。 gRPC の場合は Protocol Buffers からソースコードを生成するのがほぼ前提となっています。 protoc コマンドを利用すると .proto ファイルから各言語のサーバー・クライアントコードを生成することができます。 OpenAPI の場合、 openapi-generator や swagger-codegen などのツールを利用することで各種言語のコードを自動生成が可能です。 openapi-generator や swagger-codegen には多くの言語とフレームワークのサーバースタブと API クライアントのジェネレータが用意されています。 既存のジェネレータを使うだけでも十分に強力なのですが、さらに自前でコードジェネレータを書けばプロジェクト固有のルールでコードを生成するといったことも可能です。 OpenAPI のドキュメント自体はただの YAML/JSON なので、パースしてスキーマ定義を再帰的に読んでいけばコード生成に必要な情報を集めることができます。 Protocol Buffers からコードを生成する場合は protoc のプラグインを書く のが簡単でオススメです。 モックサーバーを使ってクライアント開発を進められる コードの自動生成の他にもスキーマからモックサーバを立ち上げるといった活用方法もあります。 Prism のようなスキーマ定義から固定のデータを返すモックサーバを立ち上げるツールを利用すれば、クライアント側の開発もしやすくなります。 特にフロントエンドとバックエンドで担当が分かれているような場合は、開発初期はモックサーバーを使って開発を始め、バックエンドの実装ができてきた頃に結合するという流れを踏むことで、フロントエンドもより早いタイミングから開発に着手することができるようになります。 実際に Prism を使ってモックサーバーを立ち上げるとこんな感じになります。 スキーマファースト開発 このような開発スタイルはスキーマファースト開発・スキーマ駆動開発などと呼ばれています。 明確な定義や出典があるわけではないのですが、スキーマファーストな開発は以下のような開発スタイル全般を指しています。 スキーマは実装言語によらない machine-readable な形で記述する ドキュメントをスキーマから自動生成する クライアント/サーバーのコードをスキーマから自動生成する 実際にスキーマファーストな開発を実践するためにはスキーマをメンテナンスするモチベーションを高く保つ必要があります。 コードも書いた上でスキーマも書かないいけないとなるとおそらくスキーマが更新されなくなっていくので、可能な限りスキーマからコードを生成する努力が必要になります。 一方、うまく実践すればスキーマという形で 100% 信頼できる API ドキュメントが手に入り、クライアント/サーバー間での齟齬も減らせるので、実践してみる価値はあるのではないかと思います。 まとめ 今回は CLINICS アプリの開発でのスキーマ言語の活用例について紹介しました。 実際に開発の中でスキーマ言語を使うことで API 仕様について把握する労力が減り、エンジニア間のコミュニケーションも取りやすくなったと感じています。 また、一部のクライアントコードは OpenAPI や Protocol Buffers から自動生成しているのですが、かなり手間が省けると同時に人間の手で書くと起こりがちなミスも防ぐことができています。 OpenAPI であれば既存の REST API の仕様を書き起こすところから使い始められるので、興味のある方はぜひ一度使ってみてはいかがでしょうか。 最後に インキュベーション本部 では「医療ヘルスケアの未来」をつくる新規事業の立ち上げに挑戦しています。そんな私たちと一緒に働いてみたいと思った方は、ぜひ以下の採用情報もチェックしてみてください。 募集の一覧 | 株式会社メドレー メドレーの採用情報はこちらからご確認ください。 www.medley.jp

こんにちは、インキュベーション本部エンジニアの加藤です。 主に CLINICS アプリ の開発を担当しています。 はじめに CLINICS アプリの開発では OpenAPI や gRPC を利用しています。 OpenAPI と gRPC の間には何の関係もないのですが、どちらも API の仕様をスキーマ言語で記述するという点では共通しています。 今回はこの API スキーマが開発にもたらすメリットについて紹介していこうと思います。 API ドキュメントとしてのスキーマ定義 既存のコードに機能を追加する際や修正を加える際に気にすることの多い部分は API の仕様ではないかと思います。 「リクエストやレスポンスはどのようなデータなのか」「この値は必須なのか、任意なのか」「データの型は数値なのか、文字列なのか」「フォーマットは決まっているのか」など、多くのことを把握する必要があります。 しかし、こういった API 仕様のドキュメントが整備されていないということも多いのではないでしょうか。 また、ドキュメントはあるけれどリクエストとレスポンスのサンプル JSON が貼ってあるだけだったり、時間が経つうちに実装とドキュメントが乖離してしまいアテにならなくなってしまっている場合もあります。 参考にできるドキュメントがない場合は、直接バックエンドの実装を見に行くこともあるのですが、目的のコードを探し出して読み解くのは意外と時間がかかります。 特に自分以外のエンジニアが実装した機能の場合、API の仕様を実装から紐解くのはかなり骨が折れる作業です。 CLINICS アプリの開発ではこういった手間を減らすために OpenAPI や gRPC を利用しています。 REST API のスキーマは OpenAPI を使って記述しています。 gRPC を利用している部分は Protocol Buffers で RPC のインターフェースが記述されるため、これが API のスキーマになっています。 OpenAPI や Protocol Buffers の定義を参照することで API の仕様が容易に把握できるため、非常に便利です。 OpenAPI や Protocol Buffers などのスキーマ言語の良い点は、宣言的な DSL でスキーマを定義できる点です。 実装言語に依存しない形での記述ができ、自然言語のような曖昧さもないためより正確に API 仕様を記述することができます。 ここからは OpenAPI や Protocol Buffers の実際に記述例を挙げながら、どういった形でスキーマを記述していくのか簡単に見ていきたいと思います。 OpenAPI OpenAPI は REST API のインターフェースを記述する仕様です。 エンドポイントのリクエストパラメータやレスポンスの構造などを JSON や YAML で記述していくことができます。 かつては Swagger という名称だったため、そちらの名前で知っているという方もいらっしゃるかもしれません。 実際の OpenAPI の定義は以下のような形になります。 openapi : 3.0.2 info : { title : OpenAPI Sample , version : 1.0.0 } paths : "/users/{user_id}" : get : parameters : - name : user_id in : path required : true schema : { type : string } responses : "200" : description : OK content : application/json : schema : type : object properties : id : { type : string } name : { type : string } age : { type : integer , nullable : true } required : [ id , name , age ] "404" : description : Not Found "500" : description : Internal Server Error 例としてユーザー ID からユーザーのデータを取得する API を記述してみました。 上記の定義を見ると、 GET: /users/{user_id} というエンドポイントがある ユーザーの ID ( user_id ) を string でパラメータとしてパスの中に埋め込む レスポンスは 200, 404, 500 が返ってくる可能性がある といったことが読み取れるかと思います。 また、レスポンスは以下のような JSON が返ってくることもスキーマから読み取ることができます。 { "id" : "12345678-1234-1234-1234-123456789abc" , "name" : "user name" , "age" : 25 } ここでは OpenAPI の記述の仕方についてあまり深く触れませんが、この他にもデータのフォーマットや省略された場合のデフォルト値などの記述なども可能です。 より詳しくは こちら を参考にしてみてください。 これらをうまく使うことでより正確に API の仕様を記述することができます。 Protocol Buffers Protocol Buffers は主に gRPC で用いられるデータのシリアライゼーション形式です。 専用のスキーマ言語を用いてデータの構造や RPC のメソッドの定義を .proto ファイルに記述していきます。 実際の .proto ファイルは以下のような形になります。 syntax = "proto3" ; package example.protobuf ; service UserService { rpc GetUser ( GetUserRequest ) returns ( GetUserResponse ); } message GetUserRequest { string id = 1 ; } message GetUserResponse { User user = 1 ; } message User { string id = 1 ; string name = 2 ; int32 age = 3 ; } 少し独特な見た目をしていますが、 message として構造体のようなデータ構造が定義されていることが見て取れると思います。 各メッセージにはフィールドが定義されており、型とフィールド名が宣言されています。 スキーマ言語を使うメリット スキーマはドキュメントの代わりとして使えるだけでなく、他にもいくつか使い道があるので紹介していこうと思います。 スキーマからソースコードを自動生成できる スキーマ言語による記述は人間にとって読みやすいだけでなく機械的に処理できる形式でもあるので、スキーマからソースコードを自動生成することも可能です。 プログラミング言語や使っているフレームワークによらず、サーバー側ではリクエストのバリデーションを、またクライアント側ではレスポンスの JSON をクラスや構造体に詰めるような処理を書くことが多いのではないでしょうか。 事前にスキーマ定義を書いている場合はスキーマを見ながらこういったコードを書き起こしていくことになるのですが、せっかく machine-readable な形のスキーマがあるのだから自動でコードを生成したくなるのが自然な考えでしょう。 自動で生成してしまえば定型のコードを書く手間を減らせるだけでなく、手書きするとどうしても起こしがちな JSON のキー名を間違えるといったミスを防ぐこともできます。 また、Web, iOS, Android などの複数プラットフォームでサービスを展開している場合でも、それぞれの実装が乖離しないように管理していくことも容易です。 gRPC の場合は Protocol Buffers からソースコードを生成するのがほぼ前提となっています。 protoc コマンドを利用すると .proto ファイルから各言語のサーバー・クライアントコードを生成することができます。 OpenAPI の場合、 openapi-generator や swagger-codegen などのツールを利用することで各種言語のコードを自動生成が可能です。 openapi-generator や swagger-codegen には多くの言語とフレームワークのサーバースタブと API クライアントのジェネレータが用意されています。 既存のジェネレータを使うだけでも十分に強力なのですが、さらに自前でコードジェネレータを書けばプロジェクト固有のルールでコードを生成するといったことも可能です。 OpenAPI のドキュメント自体はただの YAML/JSON なので、パースしてスキーマ定義を再帰的に読んでいけばコード生成に必要な情報を集めることができます。 Protocol Buffers からコードを生成する場合は protoc のプラグインを書く のが簡単でオススメです。 モックサーバーを使ってクライアント開発を進められる コードの自動生成の他にもスキーマからモックサーバを立ち上げるといった活用方法もあります。 Prism のようなスキーマ定義から固定のデータを返すモックサーバを立ち上げるツールを利用すれば、クライアント側の開発もしやすくなります。 特にフロントエンドとバックエンドで担当が分かれているような場合は、開発初期はモックサーバーを使って開発を始め、バックエンドの実装ができてきた頃に結合するという流れを踏むことで、フロントエンドもより早いタイミングから開発に着手することができるようになります。 実際に Prism を使ってモックサーバーを立ち上げるとこんな感じになります。 スキーマファースト開発 このような開発スタイルはスキーマファースト開発・スキーマ駆動開発などと呼ばれています。 明確な定義や出典があるわけではないのですが、スキーマファーストな開発は以下のような開発スタイル全般を指しています。 スキーマは実装言語によらない machine-readable な形で記述する ドキュメントをスキーマから自動生成する クライアント/サーバーのコードをスキーマから自動生成する 実際にスキーマファーストな開発を実践するためにはスキーマをメンテナンスするモチベーションを高く保つ必要があります。 コードも書いた上でスキーマも書かないいけないとなるとおそらくスキーマが更新されなくなっていくので、可能な限りスキーマからコードを生成する努力が必要になります。 一方、うまく実践すればスキーマという形で 100% 信頼できる API ドキュメントが手に入り、クライアント/サーバー間での齟齬も減らせるので、実践してみる価値はあるのではないかと思います。 まとめ 今回は CLINICS アプリの開発でのスキーマ言語の活用例について紹介しました。 実際に開発の中でスキーマ言語を使うことで API 仕様について把握する労力が減り、エンジニア間のコミュニケーションも取りやすくなったと感じています。 また、一部のクライアントコードは OpenAPI や Protocol Buffers から自動生成しているのですが、かなり手間が省けると同時に人間の手で書くと起こりがちなミスも防ぐことができています。 OpenAPI であれば既存の REST API の仕様を書き起こすところから使い始められるので、興味のある方はぜひ一度使ってみてはいかがでしょうか。 最後に インキュベーション本部 では「医療ヘルスケアの未来」をつくる新規事業の立ち上げに挑戦しています。そんな私たちと一緒に働いてみたいと思った方は、ぜひ以下の採用情報もチェックしてみてください。 募集の一覧 | 株式会社メドレー メドレーの採用情報はこちらからご確認ください。 www.medley.jp

こんにちは、インキュベーション本部エンジニアの加藤です。 主に CLINICS アプリ の開発を担当しています。 はじめに CLINICS アプリの開発では OpenAPI や gRPC を利用しています。 OpenAPI と gRPC の間には何の関係もないのですが、どちらも API の仕様をスキーマ言語で記述するという点では共通しています。 今回はこの API スキーマが開発にもたらすメリットについて紹介していこうと思います。 API ドキュメントとしてのスキーマ定義 既存のコードに機能を追加する際や修正を加える際に気にすることの多い部分は API の仕様ではないかと思います。 「リクエストやレスポンスはどのようなデータなのか」「この値は必須なのか、任意なのか」「データの型は数値なのか、文字列なのか」「フォーマットは決まっているのか」など、多くのことを把握する必要があります。 しかし、こういった API 仕様のドキュメントが整備されていないということも多いのではないでしょうか。 また、ドキュメントはあるけれどリクエストとレスポンスのサンプル JSON が貼ってあるだけだったり、時間が経つうちに実装とドキュメントが乖離してしまいアテにならなくなってしまっている場合もあります。 参考にできるドキュメントがない場合は、直接バックエンドの実装を見に行くこともあるのですが、目的のコードを探し出して読み解くのは意外と時間がかかります。 特に自分以外のエンジニアが実装した機能の場合、API の仕様を実装から紐解くのはかなり骨が折れる作業です。 CLINICS アプリの開発ではこういった手間を減らすために OpenAPI や gRPC を利用しています。 REST API のスキーマは OpenAPI を使って記述しています。 gRPC を利用している部分は Protocol Buffers で RPC のインターフェースが記述されるため、これが API のスキーマになっています。 OpenAPI や Protocol Buffers の定義を参照することで API の仕様が容易に把握できるため、非常に便利です。 OpenAPI や Protocol Buffers などのスキーマ言語の良い点は、宣言的な DSL でスキーマを定義できる点です。 実装言語に依存しない形での記述ができ、自然言語のような曖昧さもないためより正確に API 仕様を記述することができます。 ここからは OpenAPI や Protocol Buffers の実際に記述例を挙げながら、どういった形でスキーマを記述していくのか簡単に見ていきたいと思います。 OpenAPI OpenAPI は REST API のインターフェースを記述する仕様です。 エンドポイントのリクエストパラメータやレスポンスの構造などを JSON や YAML で記述していくことができます。 かつては Swagger という名称だったため、そちらの名前で知っているという方もいらっしゃるかもしれません。 実際の OpenAPI の定義は以下のような形になります。 openapi : 3.0.2 info : { title : OpenAPI Sample , version : 1.0.0 } paths : "/users/{user_id}" : get : parameters : - name : user_id in : path required : true schema : { type : string } responses : "200" : description : OK content : application/json : schema : type : object properties : id : { type : string } name : { type : string } age : { type : integer , nullable : true } required : [ id , name , age ] "404" : description : Not Found "500" : description : Internal Server Error 例としてユーザー ID からユーザーのデータを取得する API を記述してみました。 上記の定義を見ると、 GET: /users/{user_id} というエンドポイントがある ユーザーの ID ( user_id ) を string でパラメータとしてパスの中に埋め込む レスポンスは 200, 404, 500 が返ってくる可能性がある といったことが読み取れるかと思います。 また、レスポンスは以下のような JSON が返ってくることもスキーマから読み取ることができます。 { "id" : "12345678-1234-1234-1234-123456789abc" , "name" : "user name" , "age" : 25 } ここでは OpenAPI の記述の仕方についてあまり深く触れませんが、この他にもデータのフォーマットや省略された場合のデフォルト値などの記述なども可能です。 より詳しくは こちら を参考にしてみてください。 これらをうまく使うことでより正確に API の仕様を記述することができます。 Protocol Buffers Protocol Buffers は主に gRPC で用いられるデータのシリアライゼーション形式です。 専用のスキーマ言語を用いてデータの構造や RPC のメソッドの定義を .proto ファイルに記述していきます。 実際の .proto ファイルは以下のような形になります。 syntax = "proto3" ; package example.protobuf ; service UserService { rpc GetUser ( GetUserRequest ) returns ( GetUserResponse ); } message GetUserRequest { string id = 1 ; } message GetUserResponse { User user = 1 ; } message User { string id = 1 ; string name = 2 ; int32 age = 3 ; } 少し独特な見た目をしていますが、 message として構造体のようなデータ構造が定義されていることが見て取れると思います。 各メッセージにはフィールドが定義されており、型とフィールド名が宣言されています。 スキーマ言語を使うメリット スキーマはドキュメントの代わりとして使えるだけでなく、他にもいくつか使い道があるので紹介していこうと思います。 スキーマからソースコードを自動生成できる スキーマ言語による記述は人間にとって読みやすいだけでなく機械的に処理できる形式でもあるので、スキーマからソースコードを自動生成することも可能です。 プログラミング言語や使っているフレームワークによらず、サーバー側ではリクエストのバリデーションを、またクライアント側ではレスポンスの JSON をクラスや構造体に詰めるような処理を書くことが多いのではないでしょうか。 事前にスキーマ定義を書いている場合はスキーマを見ながらこういったコードを書き起こしていくことになるのですが、せっかく machine-readable な形のスキーマがあるのだから自動でコードを生成したくなるのが自然な考えでしょう。 自動で生成してしまえば定型のコードを書く手間を減らせるだけでなく、手書きするとどうしても起こしがちな JSON のキー名を間違えるといったミスを防ぐこともできます。 また、Web, iOS, Android などの複数プラットフォームでサービスを展開している場合でも、それぞれの実装が乖離しないように管理していくことも容易です。 gRPC の場合は Protocol Buffers からソースコードを生成するのがほぼ前提となっています。 protoc コマンドを利用すると .proto ファイルから各言語のサーバー・クライアントコードを生成することができます。 OpenAPI の場合、 openapi-generator や swagger-codegen などのツールを利用することで各種言語のコードを自動生成が可能です。 openapi-generator や swagger-codegen には多くの言語とフレームワークのサーバースタブと API クライアントのジェネレータが用意されています。 既存のジェネレータを使うだけでも十分に強力なのですが、さらに自前でコードジェネレータを書けばプロジェクト固有のルールでコードを生成するといったことも可能です。 OpenAPI のドキュメント自体はただの YAML/JSON なので、パースしてスキーマ定義を再帰的に読んでいけばコード生成に必要な情報を集めることができます。 Protocol Buffers からコードを生成する場合は protoc のプラグインを書く のが簡単でオススメです。 モックサーバーを使ってクライアント開発を進められる コードの自動生成の他にもスキーマからモックサーバを立ち上げるといった活用方法もあります。 Prism のようなスキーマ定義から固定のデータを返すモックサーバを立ち上げるツールを利用すれば、クライアント側の開発もしやすくなります。 特にフロントエンドとバックエンドで担当が分かれているような場合は、開発初期はモックサーバーを使って開発を始め、バックエンドの実装ができてきた頃に結合するという流れを踏むことで、フロントエンドもより早いタイミングから開発に着手することができるようになります。 実際に Prism を使ってモックサーバーを立ち上げるとこんな感じになります。 スキーマファースト開発 このような開発スタイルはスキーマファースト開発・スキーマ駆動開発などと呼ばれています。 明確な定義や出典があるわけではないのですが、スキーマファーストな開発は以下のような開発スタイル全般を指しています。 スキーマは実装言語によらない machine-readable な形で記述する ドキュメントをスキーマから自動生成する クライアント/サーバーのコードをスキーマから自動生成する 実際にスキーマファーストな開発を実践するためにはスキーマをメンテナンスするモチベーションを高く保つ必要があります。 コードも書いた上でスキーマも書かないいけないとなるとおそらくスキーマが更新されなくなっていくので、可能な限りスキーマからコードを生成する努力が必要になります。 一方、うまく実践すればスキーマという形で 100% 信頼できる API ドキュメントが手に入り、クライアント/サーバー間での齟齬も減らせるので、実践してみる価値はあるのではないかと思います。 まとめ 今回は CLINICS アプリの開発でのスキーマ言語の活用例について紹介しました。 実際に開発の中でスキーマ言語を使うことで API 仕様について把握する労力が減り、エンジニア間のコミュニケーションも取りやすくなったと感じています。 また、一部のクライアントコードは OpenAPI や Protocol Buffers から自動生成しているのですが、かなり手間が省けると同時に人間の手で書くと起こりがちなミスも防ぐことができています。 OpenAPI であれば既存の REST API の仕様を書き起こすところから使い始められるので、興味のある方はぜひ一度使ってみてはいかがでしょうか。 最後に インキュベーション本部 では「医療ヘルスケアの未来」をつくる新規事業の立ち上げに挑戦しています。そんな私たちと一緒に働いてみたいと思った方は、ぜひ以下の採用情報もチェックしてみてください。 募集の一覧 | 株式会社メドレー メドレーの採用情報はこちらからご確認ください。 www.medley.jp

こんにちは、インキュベーション本部エンジニアの加藤です。 主に CLINICS アプリ の開発を担当しています。 はじめに CLINICS アプリの開発では OpenAPI や gRPC を利用しています。 OpenAPI と gRPC の間には何の関係もないのですが、どちらも API の仕様をスキーマ言語で記述するという点では共通しています。 今回はこの API スキーマが開発にもたらすメリットについて紹介していこうと思います。 API ドキュメントとしてのスキーマ定義 既存のコードに機能を追加する際や修正を加える際に気にすることの多い部分は API の仕様ではないかと思います。 「リクエストやレスポンスはどのようなデータなのか」「この値は必須なのか、任意なのか」「データの型は数値なのか、文字列なのか」「フォーマットは決まっているのか」など、多くのことを把握する必要があります。 しかし、こういった API 仕様のドキュメントが整備されていないということも多いのではないでしょうか。 また、ドキュメントはあるけれどリクエストとレスポンスのサンプル JSON が貼ってあるだけだったり、時間が経つうちに実装とドキュメントが乖離してしまいアテにならなくなってしまっている場合もあります。 参考にできるドキュメントがない場合は、直接バックエンドの実装を見に行くこともあるのですが、目的のコードを探し出して読み解くのは意外と時間がかかります。 特に自分以外のエンジニアが実装した機能の場合、API の仕様を実装から紐解くのはかなり骨が折れる作業です。 CLINICS アプリの開発ではこういった手間を減らすために OpenAPI や gRPC を利用しています。 REST API のスキーマは OpenAPI を使って記述しています。 gRPC を利用している部分は Protocol Buffers で RPC のインターフェースが記述されるため、これが API のスキーマになっています。 OpenAPI や Protocol Buffers の定義を参照することで API の仕様が容易に把握できるため、非常に便利です。 OpenAPI や Protocol Buffers などのスキーマ言語の良い点は、宣言的な DSL でスキーマを定義できる点です。 実装言語に依存しない形での記述ができ、自然言語のような曖昧さもないためより正確に API 仕様を記述することができます。 ここからは OpenAPI や Protocol Buffers の実際に記述例を挙げながら、どういった形でスキーマを記述していくのか簡単に見ていきたいと思います。 OpenAPI OpenAPI は REST API のインターフェースを記述する仕様です。 エンドポイントのリクエストパラメータやレスポンスの構造などを JSON や YAML で記述していくことができます。 かつては Swagger という名称だったため、そちらの名前で知っているという方もいらっしゃるかもしれません。 実際の OpenAPI の定義は以下のような形になります。 openapi : 3.0.2 info : { title : OpenAPI Sample , version : 1.0.0 } paths : "/users/{user_id}" : get : parameters : - name : user_id in : path required : true schema : { type : string } responses : "200" : description : OK content : application/json : schema : type : object properties : id : { type : string } name : { type : string } age : { type : integer , nullable : true } required : [ id , name , age ] "404" : description : Not Found "500" : description : Internal Server Error 例としてユーザー ID からユーザーのデータを取得する API を記述してみました。 上記の定義を見ると、 GET: /users/{user_id} というエンドポイントがある ユーザーの ID ( user_id ) を string でパラメータとしてパスの中に埋め込む レスポンスは 200, 404, 500 が返ってくる可能性がある といったことが読み取れるかと思います。 また、レスポンスは以下のような JSON が返ってくることもスキーマから読み取ることができます。 { "id" : "12345678-1234-1234-1234-123456789abc" , "name" : "user name" , "age" : 25 } ここでは OpenAPI の記述の仕方についてあまり深く触れませんが、この他にもデータのフォーマットや省略された場合のデフォルト値などの記述なども可能です。 より詳しくは こちら を参考にしてみてください。 これらをうまく使うことでより正確に API の仕様を記述することができます。 Protocol Buffers Protocol Buffers は主に gRPC で用いられるデータのシリアライゼーション形式です。 専用のスキーマ言語を用いてデータの構造や RPC のメソッドの定義を .proto ファイルに記述していきます。 実際の .proto ファイルは以下のような形になります。 syntax = "proto3" ; package example.protobuf ; service UserService { rpc GetUser ( GetUserRequest ) returns ( GetUserResponse ); } message GetUserRequest { string id = 1 ; } message GetUserResponse { User user = 1 ; } message User { string id = 1 ; string name = 2 ; int32 age = 3 ; } 少し独特な見た目をしていますが、 message として構造体のようなデータ構造が定義されていることが見て取れると思います。 各メッセージにはフィールドが定義されており、型とフィールド名が宣言されています。 スキーマ言語を使うメリット スキーマはドキュメントの代わりとして使えるだけでなく、他にもいくつか使い道があるので紹介していこうと思います。 スキーマからソースコードを自動生成できる スキーマ言語による記述は人間にとって読みやすいだけでなく機械的に処理できる形式でもあるので、スキーマからソースコードを自動生成することも可能です。 プログラミング言語や使っているフレームワークによらず、サーバー側ではリクエストのバリデーションを、またクライアント側ではレスポンスの JSON をクラスや構造体に詰めるような処理を書くことが多いのではないでしょうか。 事前にスキーマ定義を書いている場合はスキーマを見ながらこういったコードを書き起こしていくことになるのですが、せっかく machine-readable な形のスキーマがあるのだから自動でコードを生成したくなるのが自然な考えでしょう。 自動で生成してしまえば定型のコードを書く手間を減らせるだけでなく、手書きするとどうしても起こしがちな JSON のキー名を間違えるといったミスを防ぐこともできます。 また、Web, iOS, Android などの複数プラットフォームでサービスを展開している場合でも、それぞれの実装が乖離しないように管理していくことも容易です。 gRPC の場合は Protocol Buffers からソースコードを生成するのがほぼ前提となっています。 protoc コマンドを利用すると .proto ファイルから各言語のサーバー・クライアントコードを生成することができます。 OpenAPI の場合、 openapi-generator や swagger-codegen などのツールを利用することで各種言語のコードを自動生成が可能です。 openapi-generator や swagger-codegen には多くの言語とフレームワークのサーバースタブと API クライアントのジェネレータが用意されています。 既存のジェネレータを使うだけでも十分に強力なのですが、さらに自前でコードジェネレータを書けばプロジェクト固有のルールでコードを生成するといったことも可能です。 OpenAPI のドキュメント自体はただの YAML/JSON なので、パースしてスキーマ定義を再帰的に読んでいけばコード生成に必要な情報を集めることができます。 Protocol Buffers からコードを生成する場合は protoc のプラグインを書く のが簡単でオススメです。 モックサーバーを使ってクライアント開発を進められる コードの自動生成の他にもスキーマからモックサーバを立ち上げるといった活用方法もあります。 Prism のようなスキーマ定義から固定のデータを返すモックサーバを立ち上げるツールを利用すれば、クライアント側の開発もしやすくなります。 特にフロントエンドとバックエンドで担当が分かれているような場合は、開発初期はモックサーバーを使って開発を始め、バックエンドの実装ができてきた頃に結合するという流れを踏むことで、フロントエンドもより早いタイミングから開発に着手することができるようになります。 実際に Prism を使ってモックサーバーを立ち上げるとこんな感じになります。 スキーマファースト開発 このような開発スタイルはスキーマファースト開発・スキーマ駆動開発などと呼ばれています。 明確な定義や出典があるわけではないのですが、スキーマファーストな開発は以下のような開発スタイル全般を指しています。 スキーマは実装言語によらない machine-readable な形で記述する ドキュメントをスキーマから自動生成する クライアント/サーバーのコードをスキーマから自動生成する 実際にスキーマファーストな開発を実践するためにはスキーマをメンテナンスするモチベーションを高く保つ必要があります。 コードも書いた上でスキーマも書かないいけないとなるとおそらくスキーマが更新されなくなっていくので、可能な限りスキーマからコードを生成する努力が必要になります。 一方、うまく実践すればスキーマという形で 100% 信頼できる API ドキュメントが手に入り、クライアント/サーバー間での齟齬も減らせるので、実践してみる価値はあるのではないかと思います。 まとめ 今回は CLINICS アプリの開発でのスキーマ言語の活用例について紹介しました。 実際に開発の中でスキーマ言語を使うことで API 仕様について把握する労力が減り、エンジニア間のコミュニケーションも取りやすくなったと感じています。 また、一部のクライアントコードは OpenAPI や Protocol Buffers から自動生成しているのですが、かなり手間が省けると同時に人間の手で書くと起こりがちなミスも防ぐことができています。 OpenAPI であれば既存の REST API の仕様を書き起こすところから使い始められるので、興味のある方はぜひ一度使ってみてはいかがでしょうか。 最後に インキュベーション本部 では「医療ヘルスケアの未来」をつくる新規事業の立ち上げに挑戦しています。そんな私たちと一緒に働いてみたいと思った方は、ぜひ以下の採用情報もチェックしてみてください。 募集の一覧 | 株式会社メドレー メドレーの採用情報はこちらからご確認ください。 www.medley.jp

こんにちは、インキュベーション本部エンジニアの加藤です。 主に CLINICS アプリ の開発を担当しています。 はじめに CLINICS アプリの開発では OpenAPI や gRPC を利用しています。 OpenAPI と gRPC の間には何の関係もないのですが、どちらも API の仕様をスキーマ言語で記述するという点では共通しています。 今回はこの API スキーマが開発にもたらすメリットについて紹介していこうと思います。 API ドキュメントとしてのスキーマ定義 既存のコードに機能を追加する際や修正を加える際に気にすることの多い部分は API の仕様ではないかと思います。 「リクエストやレスポンスはどのようなデータなのか」「この値は必須なのか、任意なのか」「データの型は数値なのか、文字列なのか」「フォーマットは決まっているのか」など、多くのことを把握する必要があります。 しかし、こういった API 仕様のドキュメントが整備されていないということも多いのではないでしょうか。 また、ドキュメントはあるけれどリクエストとレスポンスのサンプル JSON が貼ってあるだけだったり、時間が経つうちに実装とドキュメントが乖離してしまいアテにならなくなってしまっている場合もあります。 参考にできるドキュメントがない場合は、直接バックエンドの実装を見に行くこともあるのですが、目的のコードを探し出して読み解くのは意外と時間がかかります。 特に自分以外のエンジニアが実装した機能の場合、API の仕様を実装から紐解くのはかなり骨が折れる作業です。 CLINICS アプリの開発ではこういった手間を減らすために OpenAPI や gRPC を利用しています。 REST API のスキーマは OpenAPI を使って記述しています。 gRPC を利用している部分は Protocol Buffers で RPC のインターフェースが記述されるため、これが API のスキーマになっています。 OpenAPI や Protocol Buffers の定義を参照することで API の仕様が容易に把握できるため、非常に便利です。 OpenAPI や Protocol Buffers などのスキーマ言語の良い点は、宣言的な DSL でスキーマを定義できる点です。 実装言語に依存しない形での記述ができ、自然言語のような曖昧さもないためより正確に API 仕様を記述することができます。 ここからは OpenAPI や Protocol Buffers の実際に記述例を挙げながら、どういった形でスキーマを記述していくのか簡単に見ていきたいと思います。 OpenAPI OpenAPI は REST API のインターフェースを記述する仕様です。 エンドポイントのリクエストパラメータやレスポンスの構造などを JSON や YAML で記述していくことができます。 かつては Swagger という名称だったため、そちらの名前で知っているという方もいらっしゃるかもしれません。 実際の OpenAPI の定義は以下のような形になります。 openapi : 3.0.2 info : { title : OpenAPI Sample , version : 1.0.0 } paths : "/users/{user_id}" : get : parameters : - name : user_id in : path required : true schema : { type : string } responses : "200" : description : OK content : application/json : schema : type : object properties : id : { type : string } name : { type : string } age : { type : integer , nullable : true } required : [ id , name , age ] "404" : description : Not Found "500" : description : Internal Server Error 例としてユーザー ID からユーザーのデータを取得する API を記述してみました。 上記の定義を見ると、 GET: /users/{user_id} というエンドポイントがある ユーザーの ID ( user_id ) を string でパラメータとしてパスの中に埋め込む レスポンスは 200, 404, 500 が返ってくる可能性がある といったことが読み取れるかと思います。 また、レスポンスは以下のような JSON が返ってくることもスキーマから読み取ることができます。 { "id" : "12345678-1234-1234-1234-123456789abc" , "name" : "user name" , "age" : 25 } ここでは OpenAPI の記述の仕方についてあまり深く触れませんが、この他にもデータのフォーマットや省略された場合のデフォルト値などの記述なども可能です。 より詳しくは こちら を参考にしてみてください。 これらをうまく使うことでより正確に API の仕様を記述することができます。 Protocol Buffers Protocol Buffers は主に gRPC で用いられるデータのシリアライゼーション形式です。 専用のスキーマ言語を用いてデータの構造や RPC のメソッドの定義を .proto ファイルに記述していきます。 実際の .proto ファイルは以下のような形になります。 syntax = "proto3" ; package example.protobuf ; service UserService { rpc GetUser ( GetUserRequest ) returns ( GetUserResponse ); } message GetUserRequest { string id = 1 ; } message GetUserResponse { User user = 1 ; } message User { string id = 1 ; string name = 2 ; int32 age = 3 ; } 少し独特な見た目をしていますが、 message として構造体のようなデータ構造が定義されていることが見て取れると思います。 各メッセージにはフィールドが定義されており、型とフィールド名が宣言されています。 スキーマ言語を使うメリット スキーマはドキュメントの代わりとして使えるだけでなく、他にもいくつか使い道があるので紹介していこうと思います。 スキーマからソースコードを自動生成できる スキーマ言語による記述は人間にとって読みやすいだけでなく機械的に処理できる形式でもあるので、スキーマからソースコードを自動生成することも可能です。 プログラミング言語や使っているフレームワークによらず、サーバー側ではリクエストのバリデーションを、またクライアント側ではレスポンスの JSON をクラスや構造体に詰めるような処理を書くことが多いのではないでしょうか。 事前にスキーマ定義を書いている場合はスキーマを見ながらこういったコードを書き起こしていくことになるのですが、せっかく machine-readable な形のスキーマがあるのだから自動でコードを生成したくなるのが自然な考えでしょう。 自動で生成してしまえば定型のコードを書く手間を減らせるだけでなく、手書きするとどうしても起こしがちな JSON のキー名を間違えるといったミスを防ぐこともできます。 また、Web, iOS, Android などの複数プラットフォームでサービスを展開している場合でも、それぞれの実装が乖離しないように管理していくことも容易です。 gRPC の場合は Protocol Buffers からソースコードを生成するのがほぼ前提となっています。 protoc コマンドを利用すると .proto ファイルから各言語のサーバー・クライアントコードを生成することができます。 OpenAPI の場合、 openapi-generator や swagger-codegen などのツールを利用することで各種言語のコードを自動生成が可能です。 openapi-generator や swagger-codegen には多くの言語とフレームワークのサーバースタブと API クライアントのジェネレータが用意されています。 既存のジェネレータを使うだけでも十分に強力なのですが、さらに自前でコードジェネレータを書けばプロジェクト固有のルールでコードを生成するといったことも可能です。 OpenAPI のドキュメント自体はただの YAML/JSON なので、パースしてスキーマ定義を再帰的に読んでいけばコード生成に必要な情報を集めることができます。 Protocol Buffers からコードを生成する場合は protoc のプラグインを書く のが簡単でオススメです。 モックサーバーを使ってクライアント開発を進められる コードの自動生成の他にもスキーマからモックサーバを立ち上げるといった活用方法もあります。 Prism のようなスキーマ定義から固定のデータを返すモックサーバを立ち上げるツールを利用すれば、クライアント側の開発もしやすくなります。 特にフロントエンドとバックエンドで担当が分かれているような場合は、開発初期はモックサーバーを使って開発を始め、バックエンドの実装ができてきた頃に結合するという流れを踏むことで、フロントエンドもより早いタイミングから開発に着手することができるようになります。 実際に Prism を使ってモックサーバーを立ち上げるとこんな感じになります。 スキーマファースト開発 このような開発スタイルはスキーマファースト開発・スキーマ駆動開発などと呼ばれています。 明確な定義や出典があるわけではないのですが、スキーマファーストな開発は以下のような開発スタイル全般を指しています。 スキーマは実装言語によらない machine-readable な形で記述する ドキュメントをスキーマから自動生成する クライアント/サーバーのコードをスキーマから自動生成する 実際にスキーマファーストな開発を実践するためにはスキーマをメンテナンスするモチベーションを高く保つ必要があります。 コードも書いた上でスキーマも書かないいけないとなるとおそらくスキーマが更新されなくなっていくので、可能な限りスキーマからコードを生成する努力が必要になります。 一方、うまく実践すればスキーマという形で 100% 信頼できる API ドキュメントが手に入り、クライアント/サーバー間での齟齬も減らせるので、実践してみる価値はあるのではないかと思います。 まとめ 今回は CLINICS アプリの開発でのスキーマ言語の活用例について紹介しました。 実際に開発の中でスキーマ言語を使うことで API 仕様について把握する労力が減り、エンジニア間のコミュニケーションも取りやすくなったと感じています。 また、一部のクライアントコードは OpenAPI や Protocol Buffers から自動生成しているのですが、かなり手間が省けると同時に人間の手で書くと起こりがちなミスも防ぐことができています。 OpenAPI であれば既存の REST API の仕様を書き起こすところから使い始められるので、興味のある方はぜひ一度使ってみてはいかがでしょうか。 最後に インキュベーション本部 では「医療ヘルスケアの未来」をつくる新規事業の立ち上げに挑戦しています。そんな私たちと一緒に働いてみたいと思った方は、ぜひ以下の採用情報もチェックしてみてください。 募集の一覧 | 株式会社メドレー メドレーの採用情報はこちらからご確認ください。 www.medley.jp

こんにちは、インキュベーション本部エンジニアの加藤です。 主に CLINICS アプリ の開発を担当しています。 はじめに CLINICS アプリの開発では OpenAPI や gRPC を利用しています。 OpenAPI と gRPC の間には何の関係もないのですが、どちらも API の仕様をスキーマ言語で記述するという点では共通しています。 今回はこの API スキーマが開発にもたらすメリットについて紹介していこうと思います。 API ドキュメントとしてのスキーマ定義 既存のコードに機能を追加する際や修正を加える際に気にすることの多い部分は API の仕様ではないかと思います。 「リクエストやレスポンスはどのようなデータなのか」「この値は必須なのか、任意なのか」「データの型は数値なのか、文字列なのか」「フォーマットは決まっているのか」など、多くのことを把握する必要があります。 しかし、こういった API 仕様のドキュメントが整備されていないということも多いのではないでしょうか。 また、ドキュメントはあるけれどリクエストとレスポンスのサンプル JSON が貼ってあるだけだったり、時間が経つうちに実装とドキュメントが乖離してしまいアテにならなくなってしまっている場合もあります。 参考にできるドキュメントがない場合は、直接バックエンドの実装を見に行くこともあるのですが、目的のコードを探し出して読み解くのは意外と時間がかかります。 特に自分以外のエンジニアが実装した機能の場合、API の仕様を実装から紐解くのはかなり骨が折れる作業です。 CLINICS アプリの開発ではこういった手間を減らすために OpenAPI や gRPC を利用しています。 REST API のスキーマは OpenAPI を使って記述しています。 gRPC を利用している部分は Protocol Buffers で RPC のインターフェースが記述されるため、これが API のスキーマになっています。 OpenAPI や Protocol Buffers の定義を参照することで API の仕様が容易に把握できるため、非常に便利です。 OpenAPI や Protocol Buffers などのスキーマ言語の良い点は、宣言的な DSL でスキーマを定義できる点です。 実装言語に依存しない形での記述ができ、自然言語のような曖昧さもないためより正確に API 仕様を記述することができます。 ここからは OpenAPI や Protocol Buffers の実際に記述例を挙げながら、どういった形でスキーマを記述していくのか簡単に見ていきたいと思います。 OpenAPI OpenAPI は REST API のインターフェースを記述する仕様です。 エンドポイントのリクエストパラメータやレスポンスの構造などを JSON や YAML で記述していくことができます。 かつては Swagger という名称だったため、そちらの名前で知っているという方もいらっしゃるかもしれません。 実際の OpenAPI の定義は以下のような形になります。 openapi : 3.0.2 info : { title : OpenAPI Sample , version : 1.0.0 } paths : "/users/{user_id}" : get : parameters : - name : user_id in : path required : true schema : { type : string } responses : "200" : description : OK content : application/json : schema : type : object properties : id : { type : string } name : { type : string } age : { type : integer , nullable : true } required : [ id , name , age ] "404" : description : Not Found "500" : description : Internal Server Error 例としてユーザー ID からユーザーのデータを取得する API を記述してみました。 上記の定義を見ると、 GET: /users/{user_id} というエンドポイントがある ユーザーの ID ( user_id ) を string でパラメータとしてパスの中に埋め込む レスポンスは 200, 404, 500 が返ってくる可能性がある といったことが読み取れるかと思います。 また、レスポンスは以下のような JSON が返ってくることもスキーマから読み取ることができます。 { "id" : "12345678-1234-1234-1234-123456789abc" , "name" : "user name" , "age" : 25 } ここでは OpenAPI の記述の仕方についてあまり深く触れませんが、この他にもデータのフォーマットや省略された場合のデフォルト値などの記述なども可能です。 より詳しくは こちら を参考にしてみてください。 これらをうまく使うことでより正確に API の仕様を記述することができます。 Protocol Buffers Protocol Buffers は主に gRPC で用いられるデータのシリアライゼーション形式です。 専用のスキーマ言語を用いてデータの構造や RPC のメソッドの定義を .proto ファイルに記述していきます。 実際の .proto ファイルは以下のような形になります。 syntax = "proto3" ; package example.protobuf ; service UserService { rpc GetUser ( GetUserRequest ) returns ( GetUserResponse ); } message GetUserRequest { string id = 1 ; } message GetUserResponse { User user = 1 ; } message User { string id = 1 ; string name = 2 ; int32 age = 3 ; } 少し独特な見た目をしていますが、 message として構造体のようなデータ構造が定義されていることが見て取れると思います。 各メッセージにはフィールドが定義されており、型とフィールド名が宣言されています。 スキーマ言語を使うメリット スキーマはドキュメントの代わりとして使えるだけでなく、他にもいくつか使い道があるので紹介していこうと思います。 スキーマからソースコードを自動生成できる スキーマ言語による記述は人間にとって読みやすいだけでなく機械的に処理できる形式でもあるので、スキーマからソースコードを自動生成することも可能です。 プログラミング言語や使っているフレームワークによらず、サーバー側ではリクエストのバリデーションを、またクライアント側ではレスポンスの JSON をクラスや構造体に詰めるような処理を書くことが多いのではないでしょうか。 事前にスキーマ定義を書いている場合はスキーマを見ながらこういったコードを書き起こしていくことになるのですが、せっかく machine-readable な形のスキーマがあるのだから自動でコードを生成したくなるのが自然な考えでしょう。 自動で生成してしまえば定型のコードを書く手間を減らせるだけでなく、手書きするとどうしても起こしがちな JSON のキー名を間違えるといったミスを防ぐこともできます。 また、Web, iOS, Android などの複数プラットフォームでサービスを展開している場合でも、それぞれの実装が乖離しないように管理していくことも容易です。 gRPC の場合は Protocol Buffers からソースコードを生成するのがほぼ前提となっています。 protoc コマンドを利用すると .proto ファイルから各言語のサーバー・クライアントコードを生成することができます。 OpenAPI の場合、 openapi-generator や swagger-codegen などのツールを利用することで各種言語のコードを自動生成が可能です。 openapi-generator や swagger-codegen には多くの言語とフレームワークのサーバースタブと API クライアントのジェネレータが用意されています。 既存のジェネレータを使うだけでも十分に強力なのですが、さらに自前でコードジェネレータを書けばプロジェクト固有のルールでコードを生成するといったことも可能です。 OpenAPI のドキュメント自体はただの YAML/JSON なので、パースしてスキーマ定義を再帰的に読んでいけばコード生成に必要な情報を集めることができます。 Protocol Buffers からコードを生成する場合は protoc のプラグインを書く のが簡単でオススメです。 モックサーバーを使ってクライアント開発を進められる コードの自動生成の他にもスキーマからモックサーバを立ち上げるといった活用方法もあります。 Prism のようなスキーマ定義から固定のデータを返すモックサーバを立ち上げるツールを利用すれば、クライアント側の開発もしやすくなります。 特にフロントエンドとバックエンドで担当が分かれているような場合は、開発初期はモックサーバーを使って開発を始め、バックエンドの実装ができてきた頃に結合するという流れを踏むことで、フロントエンドもより早いタイミングから開発に着手することができるようになります。 実際に Prism を使ってモックサーバーを立ち上げるとこんな感じになります。 スキーマファースト開発 このような開発スタイルはスキーマファースト開発・スキーマ駆動開発などと呼ばれています。 明確な定義や出典があるわけではないのですが、スキーマファーストな開発は以下のような開発スタイル全般を指しています。 スキーマは実装言語によらない machine-readable な形で記述する ドキュメントをスキーマから自動生成する クライアント/サーバーのコードをスキーマから自動生成する 実際にスキーマファーストな開発を実践するためにはスキーマをメンテナンスするモチベーションを高く保つ必要があります。 コードも書いた上でスキーマも書かないいけないとなるとおそらくスキーマが更新されなくなっていくので、可能な限りスキーマからコードを生成する努力が必要になります。 一方、うまく実践すればスキーマという形で 100% 信頼できる API ドキュメントが手に入り、クライアント/サーバー間での齟齬も減らせるので、実践してみる価値はあるのではないかと思います。 まとめ 今回は CLINICS アプリの開発でのスキーマ言語の活用例について紹介しました。 実際に開発の中でスキーマ言語を使うことで API 仕様について把握する労力が減り、エンジニア間のコミュニケーションも取りやすくなったと感じています。 また、一部のクライアントコードは OpenAPI や Protocol Buffers から自動生成しているのですが、かなり手間が省けると同時に人間の手で書くと起こりがちなミスも防ぐことができています。 OpenAPI であれば既存の REST API の仕様を書き起こすところから使い始められるので、興味のある方はぜひ一度使ってみてはいかがでしょうか。 最後に インキュベーション本部 では「医療ヘルスケアの未来」をつくる新規事業の立ち上げに挑戦しています。そんな私たちと一緒に働いてみたいと思った方は、ぜひ以下の採用情報もチェックしてみてください。 募集の一覧 | 株式会社メドレー メドレーの採用情報はこちらからご確認ください。 www.medley.jp

こんにちは、インキュベーション本部エンジニアの加藤です。 主に CLINICS アプリ の開発を担当しています。 はじめに CLINICS アプリの開発では OpenAPI や gRPC を利用しています。 OpenAPI と gRPC の間には何の関係もないのですが、どちらも API の仕様をスキーマ言語で記述するという点では共通しています。 今回はこの API スキーマが開発にもたらすメリットについて紹介していこうと思います。 API ドキュメントとしてのスキーマ定義 既存のコードに機能を追加する際や修正を加える際に気にすることの多い部分は API の仕様ではないかと思います。 「リクエストやレスポンスはどのようなデータなのか」「この値は必須なのか、任意なのか」「データの型は数値なのか、文字列なのか」「フォーマットは決まっているのか」など、多くのことを把握する必要があります。 しかし、こういった API 仕様のドキュメントが整備されていないということも多いのではないでしょうか。 また、ドキュメントはあるけれどリクエストとレスポンスのサンプル JSON が貼ってあるだけだったり、時間が経つうちに実装とドキュメントが乖離してしまいアテにならなくなってしまっている場合もあります。 参考にできるドキュメントがない場合は、直接バックエンドの実装を見に行くこともあるのですが、目的のコードを探し出して読み解くのは意外と時間がかかります。 特に自分以外のエンジニアが実装した機能の場合、API の仕様を実装から紐解くのはかなり骨が折れる作業です。 CLINICS アプリの開発ではこういった手間を減らすために OpenAPI や gRPC を利用しています。 REST API のスキーマは OpenAPI を使って記述しています。 gRPC を利用している部分は Protocol Buffers で RPC のインターフェースが記述されるため、これが API のスキーマになっています。 OpenAPI や Protocol Buffers の定義を参照することで API の仕様が容易に把握できるため、非常に便利です。 OpenAPI や Protocol Buffers などのスキーマ言語の良い点は、宣言的な DSL でスキーマを定義できる点です。 実装言語に依存しない形での記述ができ、自然言語のような曖昧さもないためより正確に API 仕様を記述することができます。 ここからは OpenAPI や Protocol Buffers の実際に記述例を挙げながら、どういった形でスキーマを記述していくのか簡単に見ていきたいと思います。 OpenAPI OpenAPI は REST API のインターフェースを記述する仕様です。 エンドポイントのリクエストパラメータやレスポンスの構造などを JSON や YAML で記述していくことができます。 かつては Swagger という名称だったため、そちらの名前で知っているという方もいらっしゃるかもしれません。 実際の OpenAPI の定義は以下のような形になります。 openapi : 3.0.2 info : { title : OpenAPI Sample , version : 1.0.0 } paths : "/users/{user_id}" : get : parameters : - name : user_id in : path required : true schema : { type : string } responses : "200" : description : OK content : application/json : schema : type : object properties : id : { type : string } name : { type : string } age : { type : integer , nullable : true } required : [ id , name , age ] "404" : description : Not Found "500" : description : Internal Server Error 例としてユーザー ID からユーザーのデータを取得する API を記述してみました。 上記の定義を見ると、 GET: /users/{user_id} というエンドポイントがある ユーザーの ID ( user_id ) を string でパラメータとしてパスの中に埋め込む レスポンスは 200, 404, 500 が返ってくる可能性がある といったことが読み取れるかと思います。 また、レスポンスは以下のような JSON が返ってくることもスキーマから読み取ることができます。 { "id" : "12345678-1234-1234-1234-123456789abc" , "name" : "user name" , "age" : 25 } ここでは OpenAPI の記述の仕方についてあまり深く触れませんが、この他にもデータのフォーマットや省略された場合のデフォルト値などの記述なども可能です。 より詳しくは こちら を参考にしてみてください。 これらをうまく使うことでより正確に API の仕様を記述することができます。 Protocol Buffers Protocol Buffers は主に gRPC で用いられるデータのシリアライゼーション形式です。 専用のスキーマ言語を用いてデータの構造や RPC のメソッドの定義を .proto ファイルに記述していきます。 実際の .proto ファイルは以下のような形になります。 syntax = "proto3" ; package example.protobuf ; service UserService { rpc GetUser ( GetUserRequest ) returns ( GetUserResponse ); } message GetUserRequest { string id = 1 ; } message GetUserResponse { User user = 1 ; } message User { string id = 1 ; string name = 2 ; int32 age = 3 ; } 少し独特な見た目をしていますが、 message として構造体のようなデータ構造が定義されていることが見て取れると思います。 各メッセージにはフィールドが定義されており、型とフィールド名が宣言されています。 スキーマ言語を使うメリット スキーマはドキュメントの代わりとして使えるだけでなく、他にもいくつか使い道があるので紹介していこうと思います。 スキーマからソースコードを自動生成できる スキーマ言語による記述は人間にとって読みやすいだけでなく機械的に処理できる形式でもあるので、スキーマからソースコードを自動生成することも可能です。 プログラミング言語や使っているフレームワークによらず、サーバー側ではリクエストのバリデーションを、またクライアント側ではレスポンスの JSON をクラスや構造体に詰めるような処理を書くことが多いのではないでしょうか。 事前にスキーマ定義を書いている場合はスキーマを見ながらこういったコードを書き起こしていくことになるのですが、せっかく machine-readable な形のスキーマがあるのだから自動でコードを生成したくなるのが自然な考えでしょう。 自動で生成してしまえば定型のコードを書く手間を減らせるだけでなく、手書きするとどうしても起こしがちな JSON のキー名を間違えるといったミスを防ぐこともできます。 また、Web, iOS, Android などの複数プラットフォームでサービスを展開している場合でも、それぞれの実装が乖離しないように管理していくことも容易です。 gRPC の場合は Protocol Buffers からソースコードを生成するのがほぼ前提となっています。 protoc コマンドを利用すると .proto ファイルから各言語のサーバー・クライアントコードを生成することができます。 OpenAPI の場合、 openapi-generator や swagger-codegen などのツールを利用することで各種言語のコードを自動生成が可能です。 openapi-generator や swagger-codegen には多くの言語とフレームワークのサーバースタブと API クライアントのジェネレータが用意されています。 既存のジェネレータを使うだけでも十分に強力なのですが、さらに自前でコードジェネレータを書けばプロジェクト固有のルールでコードを生成するといったことも可能です。 OpenAPI のドキュメント自体はただの YAML/JSON なので、パースしてスキーマ定義を再帰的に読んでいけばコード生成に必要な情報を集めることができます。 Protocol Buffers からコードを生成する場合は protoc のプラグインを書く のが簡単でオススメです。 モックサーバーを使ってクライアント開発を進められる コードの自動生成の他にもスキーマからモックサーバを立ち上げるといった活用方法もあります。 Prism のようなスキーマ定義から固定のデータを返すモックサーバを立ち上げるツールを利用すれば、クライアント側の開発もしやすくなります。 特にフロントエンドとバックエンドで担当が分かれているような場合は、開発初期はモックサーバーを使って開発を始め、バックエンドの実装ができてきた頃に結合するという流れを踏むことで、フロントエンドもより早いタイミングから開発に着手することができるようになります。 実際に Prism を使ってモックサーバーを立ち上げるとこんな感じになります。 スキーマファースト開発 このような開発スタイルはスキーマファースト開発・スキーマ駆動開発などと呼ばれています。 明確な定義や出典があるわけではないのですが、スキーマファーストな開発は以下のような開発スタイル全般を指しています。 スキーマは実装言語によらない machine-readable な形で記述する ドキュメントをスキーマから自動生成する クライアント/サーバーのコードをスキーマから自動生成する 実際にスキーマファーストな開発を実践するためにはスキーマをメンテナンスするモチベーションを高く保つ必要があります。 コードも書いた上でスキーマも書かないいけないとなるとおそらくスキーマが更新されなくなっていくので、可能な限りスキーマからコードを生成する努力が必要になります。 一方、うまく実践すればスキーマという形で 100% 信頼できる API ドキュメントが手に入り、クライアント/サーバー間での齟齬も減らせるので、実践してみる価値はあるのではないかと思います。 まとめ 今回は CLINICS アプリの開発でのスキーマ言語の活用例について紹介しました。 実際に開発の中でスキーマ言語を使うことで API 仕様について把握する労力が減り、エンジニア間のコミュニケーションも取りやすくなったと感じています。 また、一部のクライアントコードは OpenAPI や Protocol Buffers から自動生成しているのですが、かなり手間が省けると同時に人間の手で書くと起こりがちなミスも防ぐことができています。 OpenAPI であれば既存の REST API の仕様を書き起こすところから使い始められるので、興味のある方はぜひ一度使ってみてはいかがでしょうか。 最後に インキュベーション本部 では「医療ヘルスケアの未来」をつくる新規事業の立ち上げに挑戦しています。そんな私たちと一緒に働いてみたいと思った方は、ぜひ以下の採用情報もチェックしてみてください。 https://www.medley.jp/jobs/

こんにちは、インキュベーション本部エンジニアの加藤です。 主に CLINICS アプリ の開発を担当しています。 はじめに CLINICS アプリの開発では OpenAPI や gRPC を利用しています。 OpenAPI と gRPC の間には何の関係もないのですが、どちらも API の仕様をスキーマ言語で記述するという点では共通しています。 今回はこの API スキーマが開発にもたらすメリットについて紹介していこうと思います。 API ドキュメントとしてのスキーマ定義 既存のコードに機能を追加する際や修正を加える際に気にすることの多い部分は API の仕様ではないかと思います。 「リクエストやレスポンスはどのようなデータなのか」「この値は必須なのか、任意なのか」「データの型は数値なのか、文字列なのか」「フォーマットは決まっているのか」など、多くのことを把握する必要があります。 しかし、こういった API 仕様のドキュメントが整備されていないということも多いのではないでしょうか。 また、ドキュメントはあるけれどリクエストとレスポンスのサンプル JSON が貼ってあるだけだったり、時間が経つうちに実装とドキュメントが乖離してしまいアテにならなくなってしまっている場合もあります。 参考にできるドキュメントがない場合は、直接バックエンドの実装を見に行くこともあるのですが、目的のコードを探し出して読み解くのは意外と時間がかかります。 特に自分以外のエンジニアが実装した機能の場合、API の仕様を実装から紐解くのはかなり骨が折れる作業です。 CLINICS アプリの開発ではこういった手間を減らすために OpenAPI や gRPC を利用しています。 REST API のスキーマは OpenAPI を使って記述しています。 gRPC を利用している部分は Protocol Buffers で RPC のインターフェースが記述されるため、これが API のスキーマになっています。 OpenAPI や Protocol Buffers の定義を参照することで API の仕様が容易に把握できるため、非常に便利です。 OpenAPI や Protocol Buffers などのスキーマ言語の良い点は、宣言的な DSL でスキーマを定義できる点です。 実装言語に依存しない形での記述ができ、自然言語のような曖昧さもないためより正確に API 仕様を記述することができます。 ここからは OpenAPI や Protocol Buffers の実際に記述例を挙げながら、どういった形でスキーマを記述していくのか簡単に見ていきたいと思います。 OpenAPI OpenAPI は REST API のインターフェースを記述する仕様です。 エンドポイントのリクエストパラメータやレスポンスの構造などを JSON や YAML で記述していくことができます。 かつては Swagger という名称だったため、そちらの名前で知っているという方もいらっしゃるかもしれません。 実際の OpenAPI の定義は以下のような形になります。 openapi : 3.0.2 info : { title : OpenAPI Sample , version : 1.0.0 } paths : "/users/{user_id}" : get : parameters : - name : user_id in : path required : true schema : { type : string } responses : "200" : description : OK content : application/json : schema : type : object properties : id : { type : string } name : { type : string } age : { type : integer , nullable : true } required : [ id , name , age ] "404" : description : Not Found "500" : description : Internal Server Error 例としてユーザー ID からユーザーのデータを取得する API を記述してみました。 上記の定義を見ると、 GET: /users/{user_id} というエンドポイントがある ユーザーの ID ( user_id ) を string でパラメータとしてパスの中に埋め込む レスポンスは 200, 404, 500 が返ってくる可能性がある といったことが読み取れるかと思います。 また、レスポンスは以下のような JSON が返ってくることもスキーマから読み取ることができます。 { "id" : "12345678-1234-1234-1234-123456789abc" , "name" : "user name" , "age" : 25 } ここでは OpenAPI の記述の仕方についてあまり深く触れませんが、この他にもデータのフォーマットや省略された場合のデフォルト値などの記述なども可能です。 より詳しくは こちら を参考にしてみてください。 これらをうまく使うことでより正確に API の仕様を記述することができます。 Protocol Buffers Protocol Buffers は主に gRPC で用いられるデータのシリアライゼーション形式です。 専用のスキーマ言語を用いてデータの構造や RPC のメソッドの定義を .proto ファイルに記述していきます。 実際の .proto ファイルは以下のような形になります。 syntax = "proto3" ; package example.protobuf ; service UserService { rpc GetUser ( GetUserRequest ) returns ( GetUserResponse ); } message GetUserRequest { string id = 1 ; } message GetUserResponse { User user = 1 ; } message User { string id = 1 ; string name = 2 ; int32 age = 3 ; } 少し独特な見た目をしていますが、 message として構造体のようなデータ構造が定義されていることが見て取れると思います。 各メッセージにはフィールドが定義されており、型とフィールド名が宣言されています。 スキーマ言語を使うメリット スキーマはドキュメントの代わりとして使えるだけでなく、他にもいくつか使い道があるので紹介していこうと思います。 スキーマからソースコードを自動生成できる スキーマ言語による記述は人間にとって読みやすいだけでなく機械的に処理できる形式でもあるので、スキーマからソースコードを自動生成することも可能です。 プログラミング言語や使っているフレームワークによらず、サーバー側ではリクエストのバリデーションを、またクライアント側ではレスポンスの JSON をクラスや構造体に詰めるような処理を書くことが多いのではないでしょうか。 事前にスキーマ定義を書いている場合はスキーマを見ながらこういったコードを書き起こしていくことになるのですが、せっかく machine-readable な形のスキーマがあるのだから自動でコードを生成したくなるのが自然な考えでしょう。 自動で生成してしまえば定型のコードを書く手間を減らせるだけでなく、手書きするとどうしても起こしがちな JSON のキー名を間違えるといったミスを防ぐこともできます。 また、Web, iOS, Android などの複数プラットフォームでサービスを展開している場合でも、それぞれの実装が乖離しないように管理していくことも容易です。 gRPC の場合は Protocol Buffers からソースコードを生成するのがほぼ前提となっています。 protoc コマンドを利用すると .proto ファイルから各言語のサーバー・クライアントコードを生成することができます。 OpenAPI の場合、 openapi-generator や swagger-codegen などのツールを利用することで各種言語のコードを自動生成が可能です。 openapi-generator や swagger-codegen には多くの言語とフレームワークのサーバースタブと API クライアントのジェネレータが用意されています。 既存のジェネレータを使うだけでも十分に強力なのですが、さらに自前でコードジェネレータを書けばプロジェクト固有のルールでコードを生成するといったことも可能です。 OpenAPI のドキュメント自体はただの YAML/JSON なので、パースしてスキーマ定義を再帰的に読んでいけばコード生成に必要な情報を集めることができます。 Protocol Buffers からコードを生成する場合は protoc のプラグインを書く のが簡単でオススメです。 モックサーバーを使ってクライアント開発を進められる コードの自動生成の他にもスキーマからモックサーバを立ち上げるといった活用方法もあります。 Prism のようなスキーマ定義から固定のデータを返すモックサーバを立ち上げるツールを利用すれば、クライアント側の開発もしやすくなります。 特にフロントエンドとバックエンドで担当が分かれているような場合は、開発初期はモックサーバーを使って開発を始め、バックエンドの実装ができてきた頃に結合するという流れを踏むことで、フロントエンドもより早いタイミングから開発に着手することができるようになります。 実際に Prism を使ってモックサーバーを立ち上げるとこんな感じになります。 スキーマファースト開発 このような開発スタイルはスキーマファースト開発・スキーマ駆動開発などと呼ばれています。 明確な定義や出典があるわけではないのですが、スキーマファーストな開発は以下のような開発スタイル全般を指しています。 スキーマは実装言語によらない machine-readable な形で記述する ドキュメントをスキーマから自動生成する クライアント/サーバーのコードをスキーマから自動生成する 実際にスキーマファーストな開発を実践するためにはスキーマをメンテナンスするモチベーションを高く保つ必要があります。 コードも書いた上でスキーマも書かないいけないとなるとおそらくスキーマが更新されなくなっていくので、可能な限りスキーマからコードを生成する努力が必要になります。 一方、うまく実践すればスキーマという形で 100% 信頼できる API ドキュメントが手に入り、クライアント/サーバー間での齟齬も減らせるので、実践してみる価値はあるのではないかと思います。 まとめ 今回は CLINICS アプリの開発でのスキーマ言語の活用例について紹介しました。 実際に開発の中でスキーマ言語を使うことで API 仕様について把握する労力が減り、エンジニア間のコミュニケーションも取りやすくなったと感じています。 また、一部のクライアントコードは OpenAPI や Protocol Buffers から自動生成しているのですが、かなり手間が省けると同時に人間の手で書くと起こりがちなミスも防ぐことができています。 OpenAPI であれば既存の REST API の仕様を書き起こすところから使い始められるので、興味のある方はぜひ一度使ってみてはいかがでしょうか。 最後に インキュベーション本部 では「医療ヘルスケアの未来」をつくる新規事業の立ち上げに挑戦しています。そんな私たちと一緒に働いてみたいと思った方は、ぜひ以下の採用情報もチェックしてみてください。 募集の一覧 | 株式会社メドレー メドレーの採用情報はこちらからご確認ください。 www.medley.jp

こんにちは、19 新卒の桶谷です。現在は CLINICS で検査周りの開発を担当しています。 最近は、私自身が基礎疾患持ちということもあり、社会情勢を考慮してフルリモートで業務に勤しんでいます。オンラインコミュニケーションは対面と比べ、意識しなければならない点が多く、慣れが必要であると日々感じています。少しでも対面に近い環境を実現するために、一眼レフカメラを Web カメラとして代用したり、ダイナミックマイクを使用してクリアな音声を届けられるように作業環境の改善に取り組んでいます。 今回は CLINICS 開発チームで課題となっていた「オンボーディングやキャッチアップに時間がかかる問題」を解決するために行った、横軸の取り組みについて紹介します。 はじめに CLINICS 開発チームではクラウド診療支援システム「 CLINICS 」の機能として主に電子カルテ、オンライン診療、予約システムなどの機能の開発を行っています。医療システムの開発において医療業務知識は必要不可欠であり、例えば「会計」や「検査」といった医療機関で行われる業務に関する理解が要求されます。そのため、各々が日々キャッチアップに勤しんでいる一方、ひとつひとつの業務が複雑であるために、複数の機能を横断したプロダクト理解、全体把握が難しい課題がありました。そこで、この問題を解決するべく「横軸勉強会」と題して、CLINICS のドメイン知識共有会を行うことにしました。 ドメイン知識共有会の概要 ドメイン知識共有会は各々が携わった中で蓄積してきた業務知識や開発の背景を共有する会です。本会は毎週 1 時間トピックに沿ってオンライン(Google Meet)で実施します。あらかじめトピック、発表者、ファシリテーターを指定し、発表者には簡単な資料を用意してもらいます。加えて参加者には以下のことを意識してもらいました。 発表者は対話型の発表を意識しフラットな雰囲気をつくる 参加者はチャットを用いて思ったことをつぶやく 各トピックは医療システムを開発する上で必要なドメイン知識を切り口として、技術寄りの内容となっています。発表者によっては勉強会後の宿題が用意されたり、おすすめの本紹介があったりと多種多様です。発表形式をあえて定めないことで、各回ごとに発表者の個性が出るというのも面白みの一つだと思います。特に宿題があった回では、後日にフィードバック会が設けられ知識の定着に繋がりました。 実際に行ったトピック 実際の様子 ドメイン知識共有会を終えて 今回ドメイン知識共有会を通して、機能の実装背景や概要を幅広く知ることができました。「会計業務の複雑さ」や「受付から診察までの動線設計」などのこれまでは共有する機会がなかった個々が持っている知識・知見を学ぶことができ、チーム全体でドメイン知識に関する認識合わせをする良い機会となりました。 最後に勉強会の振り返りを行ったところ、以下のような意見がありました。 ドメイン知識共有会を通してチーム力が上がってきている 勘違いしていた知識を訂正できた 相互理解が深まりチーム全体としてコミュニケーションのハードルを下げることができた 各専門領域に関するドキュメントを一箇所にまとめることができた ポジティブな意見が多く、取り組みの結果としてチームの基礎力向上にも繋がったと感じています。加えて、ドメイン知識共有会用に作成した資料はドキュメントとして残るため、オンボーディング資料などに活用ができそうです。しかしながら、以下のような問題もあります。 発表者の準備コストが高い 概要説明で終わってしまい即日業務で使用できる内容ではない 学んだことを深堀りできていないため知識の定着に繋がらない 上記については、例えば発表者を 2 人ペアにして準備コストを分散させたり、宿題を出して次回にフィードバックする、開発チーム以外も気軽に参加ができるようにライトなトピックを追加するなど、今後のドメイン知識共有会のなかで改善していきたいと思います。 さいごに 今回は CLINICS 開発チームで行った横軸の取り組みについて紹介させていただきました。 横軸でお互いをフォローしあうような「情報共有の場」を作ることで、より良い組織になっていくと感じています。今後、さらにプロダクトの機能が増えるとともに事業部全体として、関わるメンバーが増えるため、横軸での知識共有の仕組みは事業部を含めて必要であると考えています。開発チームに限らずに、プロダクトに関わるメンバーを巻き込み、組織コミュニケーションの改善を続けていきたいです。 最後までお読みいただきありがとうございました。 募集の一覧 | 株式会社メドレー メドレーの採用情報はこちらからご確認ください。 www.medley.jp

こんにちは、19 新卒の桶谷です。現在は CLINICS で検査周りの開発を担当しています。 最近は、私自身が基礎疾患持ちということもあり、社会情勢を考慮してフルリモートで業務に勤しんでいます。オンラインコミュニケーションは対面と比べ、意識しなければならない点が多く、慣れが必要であると日々感じています。少しでも対面に近い環境を実現するために、一眼レフカメラを Web カメラとして代用したり、ダイナミックマイクを使用してクリアな音声を届けられるように作業環境の改善に取り組んでいます。 今回は CLINICS 開発チームで課題となっていた「オンボーディングやキャッチアップに時間がかかる問題」を解決するために行った、横軸の取り組みについて紹介します。 はじめに CLINICS 開発チームではクラウド診療支援システム「 CLINICS 」の機能として主に電子カルテ、オンライン診療、予約システムなどの機能の開発を行っています。医療システムの開発において医療業務知識は必要不可欠であり、例えば「会計」や「検査」といった医療機関で行われる業務に関する理解が要求されます。そのため、各々が日々キャッチアップに勤しんでいる一方、ひとつひとつの業務が複雑であるために、複数の機能を横断したプロダクト理解、全体把握が難しい課題がありました。そこで、この問題を解決するべく「横軸勉強会」と題して、CLINICS のドメイン知識共有会を行うことにしました。 ドメイン知識共有会の概要 ドメイン知識共有会は各々が携わった中で蓄積してきた業務知識や開発の背景を共有する会です。本会は毎週 1 時間トピックに沿ってオンライン(Google Meet)で実施します。あらかじめトピック、発表者、ファシリテーターを指定し、発表者には簡単な資料を用意してもらいます。加えて参加者には以下のことを意識してもらいました。 発表者は対話型の発表を意識しフラットな雰囲気をつくる 参加者はチャットを用いて思ったことをつぶやく 各トピックは医療システムを開発する上で必要なドメイン知識を切り口として、技術寄りの内容となっています。発表者によっては勉強会後の宿題が用意されたり、おすすめの本紹介があったりと多種多様です。発表形式をあえて定めないことで、各回ごとに発表者の個性が出るというのも面白みの一つだと思います。特に宿題があった回では、後日にフィードバック会が設けられ知識の定着に繋がりました。 実際に行ったトピック 実際の様子 ドメイン知識共有会を終えて 今回ドメイン知識共有会を通して、機能の実装背景や概要を幅広く知ることができました。「会計業務の複雑さ」や「受付から診察までの動線設計」などのこれまでは共有する機会がなかった個々が持っている知識・知見を学ぶことができ、チーム全体でドメイン知識に関する認識合わせをする良い機会となりました。 最後に勉強会の振り返りを行ったところ、以下のような意見がありました。 ドメイン知識共有会を通してチーム力が上がってきている 勘違いしていた知識を訂正できた 相互理解が深まりチーム全体としてコミュニケーションのハードルを下げることができた 各専門領域に関するドキュメントを一箇所にまとめることができた ポジティブな意見が多く、取り組みの結果としてチームの基礎力向上にも繋がったと感じています。加えて、ドメイン知識共有会用に作成した資料はドキュメントとして残るため、オンボーディング資料などに活用ができそうです。しかしながら、以下のような問題もあります。 発表者の準備コストが高い 概要説明で終わってしまい即日業務で使用できる内容ではない 学んだことを深堀りできていないため知識の定着に繋がらない 上記については、例えば発表者を 2 人ペアにして準備コストを分散させたり、宿題を出して次回にフィードバックする、開発チーム以外も気軽に参加ができるようにライトなトピックを追加するなど、今後のドメイン知識共有会のなかで改善していきたいと思います。 さいごに 今回は CLINICS 開発チームで行った横軸の取り組みについて紹介させていただきました。 横軸でお互いをフォローしあうような「情報共有の場」を作ることで、より良い組織になっていくと感じています。今後、さらにプロダクトの機能が増えるとともに事業部全体として、関わるメンバーが増えるため、横軸での知識共有の仕組みは事業部を含めて必要であると考えています。開発チームに限らずに、プロダクトに関わるメンバーを巻き込み、組織コミュニケーションの改善を続けていきたいです。 最後までお読みいただきありがとうございました。 募集の一覧 | 株式会社メドレー メドレーの採用情報はこちらからご確認ください。 www.medley.jp

こんにちは、19 新卒の桶谷です。現在は CLINICS で検査周りの開発を担当しています。 最近は、私自身が基礎疾患持ちということもあり、社会情勢を考慮してフルリモートで業務に勤しんでいます。オンラインコミュニケーションは対面と比べ、意識しなければならない点が多く、慣れが必要であると日々感じています。少しでも対面に近い環境を実現するために、一眼レフカメラを Web カメラとして代用したり、ダイナミックマイクを使用してクリアな音声を届けられるように作業環境の改善に取り組んでいます。 今回は CLINICS 開発チームで課題となっていた「オンボーディングやキャッチアップに時間がかかる問題」を解決するために行った、横軸の取り組みについて紹介します。 はじめに CLINICS 開発チームではクラウド診療支援システム「 CLINICS 」の機能として主に電子カルテ、オンライン診療、予約システムなどの機能の開発を行っています。医療システムの開発において医療業務知識は必要不可欠であり、例えば「会計」や「検査」といった医療機関で行われる業務に関する理解が要求されます。そのため、各々が日々キャッチアップに勤しんでいる一方、ひとつひとつの業務が複雑であるために、複数の機能を横断したプロダクト理解、全体把握が難しい課題がありました。そこで、この問題を解決するべく「横軸勉強会」と題して、CLINICS のドメイン知識共有会を行うことにしました。 ドメイン知識共有会の概要 ドメイン知識共有会は各々が携わった中で蓄積してきた業務知識や開発の背景を共有する会です。本会は毎週 1 時間トピックに沿ってオンライン(Google Meet)で実施します。あらかじめトピック、発表者、ファシリテーターを指定し、発表者には簡単な資料を用意してもらいます。加えて参加者には以下のことを意識してもらいました。 発表者は対話型の発表を意識しフラットな雰囲気をつくる 参加者はチャットを用いて思ったことをつぶやく 各トピックは医療システムを開発する上で必要なドメイン知識を切り口として、技術寄りの内容となっています。発表者によっては勉強会後の宿題が用意されたり、おすすめの本紹介があったりと多種多様です。発表形式をあえて定めないことで、各回ごとに発表者の個性が出るというのも面白みの一つだと思います。特に宿題があった回では、後日にフィードバック会が設けられ知識の定着に繋がりました。 実際に行ったトピック 実際の様子 ドメイン知識共有会を終えて 今回ドメイン知識共有会を通して、機能の実装背景や概要を幅広く知ることができました。「会計業務の複雑さ」や「受付から診察までの動線設計」などのこれまでは共有する機会がなかった個々が持っている知識・知見を学ぶことができ、チーム全体でドメイン知識に関する認識合わせをする良い機会となりました。 最後に勉強会の振り返りを行ったところ、以下のような意見がありました。 ドメイン知識共有会を通してチーム力が上がってきている 勘違いしていた知識を訂正できた 相互理解が深まりチーム全体としてコミュニケーションのハードルを下げることができた 各専門領域に関するドキュメントを一箇所にまとめることができた ポジティブな意見が多く、取り組みの結果としてチームの基礎力向上にも繋がったと感じています。加えて、ドメイン知識共有会用に作成した資料はドキュメントとして残るため、オンボーディング資料などに活用ができそうです。しかしながら、以下のような問題もあります。 発表者の準備コストが高い 概要説明で終わってしまい即日業務で使用できる内容ではない 学んだことを深堀りできていないため知識の定着に繋がらない 上記については、例えば発表者を 2 人ペアにして準備コストを分散させたり、宿題を出して次回にフィードバックする、開発チーム以外も気軽に参加ができるようにライトなトピックを追加するなど、今後のドメイン知識共有会のなかで改善していきたいと思います。 さいごに 今回は CLINICS 開発チームで行った横軸の取り組みについて紹介させていただきました。 横軸でお互いをフォローしあうような「情報共有の場」を作ることで、より良い組織になっていくと感じています。今後、さらにプロダクトの機能が増えるとともに事業部全体として、関わるメンバーが増えるため、横軸での知識共有の仕組みは事業部を含めて必要であると考えています。開発チームに限らずに、プロダクトに関わるメンバーを巻き込み、組織コミュニケーションの改善を続けていきたいです。 最後までお読みいただきありがとうございました。 募集の一覧 | 株式会社メドレー メドレーの採用情報はこちらからご確認ください。 www.medley.jp

こんにちは、19 新卒の桶谷です。現在は CLINICS で検査周りの開発を担当しています。 最近は、私自身が基礎疾患持ちということもあり、社会情勢を考慮してフルリモートで業務に勤しんでいます。オンラインコミュニケーションは対面と比べ、意識しなければならない点が多く、慣れが必要であると日々感じています。少しでも対面に近い環境を実現するために、一眼レフカメラを Web カメラとして代用したり、ダイナミックマイクを使用してクリアな音声を届けられるように作業環境の改善に取り組んでいます。 今回は CLINICS 開発チームで課題となっていた「オンボーディングやキャッチアップに時間がかかる問題」を解決するために行った、横軸の取り組みについて紹介します。 はじめに CLINICS 開発チームではクラウド診療支援システム「 CLINICS 」の機能として主に電子カルテ、オンライン診療、予約システムなどの機能の開発を行っています。医療システムの開発において医療業務知識は必要不可欠であり、例えば「会計」や「検査」といった医療機関で行われる業務に関する理解が要求されます。そのため、各々が日々キャッチアップに勤しんでいる一方、ひとつひとつの業務が複雑であるために、複数の機能を横断したプロダクト理解、全体把握が難しい課題がありました。そこで、この問題を解決するべく「横軸勉強会」と題して、CLINICS のドメイン知識共有会を行うことにしました。 ドメイン知識共有会の概要 ドメイン知識共有会は各々が携わった中で蓄積してきた業務知識や開発の背景を共有する会です。本会は毎週 1 時間トピックに沿ってオンライン(Google Meet)で実施します。あらかじめトピック、発表者、ファシリテーターを指定し、発表者には簡単な資料を用意してもらいます。加えて参加者には以下のことを意識してもらいました。 発表者は対話型の発表を意識しフラットな雰囲気をつくる 参加者はチャットを用いて思ったことをつぶやく 各トピックは医療システムを開発する上で必要なドメイン知識を切り口として、技術寄りの内容となっています。発表者によっては勉強会後の宿題が用意されたり、おすすめの本紹介があったりと多種多様です。発表形式をあえて定めないことで、各回ごとに発表者の個性が出るというのも面白みの一つだと思います。特に宿題があった回では、後日にフィードバック会が設けられ知識の定着に繋がりました。 実際に行ったトピック 実際の様子 ドメイン知識共有会を終えて 今回ドメイン知識共有会を通して、機能の実装背景や概要を幅広く知ることができました。「会計業務の複雑さ」や「受付から診察までの動線設計」などのこれまでは共有する機会がなかった個々が持っている知識・知見を学ぶことができ、チーム全体でドメイン知識に関する認識合わせをする良い機会となりました。 最後に勉強会の振り返りを行ったところ、以下のような意見がありました。 ドメイン知識共有会を通してチーム力が上がってきている 勘違いしていた知識を訂正できた 相互理解が深まりチーム全体としてコミュニケーションのハードルを下げることができた 各専門領域に関するドキュメントを一箇所にまとめることができた ポジティブな意見が多く、取り組みの結果としてチームの基礎力向上にも繋がったと感じています。加えて、ドメイン知識共有会用に作成した資料はドキュメントとして残るため、オンボーディング資料などに活用ができそうです。しかしながら、以下のような問題もあります。 発表者の準備コストが高い 概要説明で終わってしまい即日業務で使用できる内容ではない 学んだことを深堀りできていないため知識の定着に繋がらない 上記については、例えば発表者を 2 人ペアにして準備コストを分散させたり、宿題を出して次回にフィードバックする、開発チーム以外も気軽に参加ができるようにライトなトピックを追加するなど、今後のドメイン知識共有会のなかで改善していきたいと思います。 さいごに 今回は CLINICS 開発チームで行った横軸の取り組みについて紹介させていただきました。 横軸でお互いをフォローしあうような「情報共有の場」を作ることで、より良い組織になっていくと感じています。今後、さらにプロダクトの機能が増えるとともに事業部全体として、関わるメンバーが増えるため、横軸での知識共有の仕組みは事業部を含めて必要であると考えています。開発チームに限らずに、プロダクトに関わるメンバーを巻き込み、組織コミュニケーションの改善を続けていきたいです。 最後までお読みいただきありがとうございました。 募集の一覧 | 株式会社メドレー メドレーの採用情報はこちらからご確認ください。 www.medley.jp

こんにちは、19 新卒の桶谷です。現在は CLINICS で検査周りの開発を担当しています。 最近は、私自身が基礎疾患持ちということもあり、社会情勢を考慮してフルリモートで業務に勤しんでいます。オンラインコミュニケーションは対面と比べ、意識しなければならない点が多く、慣れが必要であると日々感じています。少しでも対面に近い環境を実現するために、一眼レフカメラを Web カメラとして代用したり、ダイナミックマイクを使用してクリアな音声を届けられるように作業環境の改善に取り組んでいます。 今回は CLINICS 開発チームで課題となっていた「オンボーディングやキャッチアップに時間がかかる問題」を解決するために行った、横軸の取り組みについて紹介します。 はじめに CLINICS 開発チームではクラウド診療支援システム「 CLINICS 」の機能として主に電子カルテ、オンライン診療、予約システムなどの機能の開発を行っています。医療システムの開発において医療業務知識は必要不可欠であり、例えば「会計」や「検査」といった医療機関で行われる業務に関する理解が要求されます。そのため、各々が日々キャッチアップに勤しんでいる一方、ひとつひとつの業務が複雑であるために、複数の機能を横断したプロダクト理解、全体把握が難しい課題がありました。そこで、この問題を解決するべく「横軸勉強会」と題して、CLINICS のドメイン知識共有会を行うことにしました。 ドメイン知識共有会の概要 ドメイン知識共有会は各々が携わった中で蓄積してきた業務知識や開発の背景を共有する会です。本会は毎週 1 時間トピックに沿ってオンライン(Google Meet)で実施します。あらかじめトピック、発表者、ファシリテーターを指定し、発表者には簡単な資料を用意してもらいます。加えて参加者には以下のことを意識してもらいました。 発表者は対話型の発表を意識しフラットな雰囲気をつくる 参加者はチャットを用いて思ったことをつぶやく 各トピックは医療システムを開発する上で必要なドメイン知識を切り口として、技術寄りの内容となっています。発表者によっては勉強会後の宿題が用意されたり、おすすめの本紹介があったりと多種多様です。発表形式をあえて定めないことで、各回ごとに発表者の個性が出るというのも面白みの一つだと思います。特に宿題があった回では、後日にフィードバック会が設けられ知識の定着に繋がりました。 実際に行ったトピック 実際の様子 ドメイン知識共有会を終えて 今回ドメイン知識共有会を通して、機能の実装背景や概要を幅広く知ることができました。「会計業務の複雑さ」や「受付から診察までの動線設計」などのこれまでは共有する機会がなかった個々が持っている知識・知見を学ぶことができ、チーム全体でドメイン知識に関する認識合わせをする良い機会となりました。 最後に勉強会の振り返りを行ったところ、以下のような意見がありました。 ドメイン知識共有会を通してチーム力が上がってきている 勘違いしていた知識を訂正できた 相互理解が深まりチーム全体としてコミュニケーションのハードルを下げることができた 各専門領域に関するドキュメントを一箇所にまとめることができた ポジティブな意見が多く、取り組みの結果としてチームの基礎力向上にも繋がったと感じています。加えて、ドメイン知識共有会用に作成した資料はドキュメントとして残るため、オンボーディング資料などに活用ができそうです。しかしながら、以下のような問題もあります。 発表者の準備コストが高い 概要説明で終わってしまい即日業務で使用できる内容ではない 学んだことを深堀りできていないため知識の定着に繋がらない 上記については、例えば発表者を 2 人ペアにして準備コストを分散させたり、宿題を出して次回にフィードバックする、開発チーム以外も気軽に参加ができるようにライトなトピックを追加するなど、今後のドメイン知識共有会のなかで改善していきたいと思います。 さいごに 今回は CLINICS 開発チームで行った横軸の取り組みについて紹介させていただきました。 横軸でお互いをフォローしあうような「情報共有の場」を作ることで、より良い組織になっていくと感じています。今後、さらにプロダクトの機能が増えるとともに事業部全体として、関わるメンバーが増えるため、横軸での知識共有の仕組みは事業部を含めて必要であると考えています。開発チームに限らずに、プロダクトに関わるメンバーを巻き込み、組織コミュニケーションの改善を続けていきたいです。 最後までお読みいただきありがとうございました。 https://www.medley.jp/jobs/

こんにちは、19 新卒の桶谷です。現在は CLINICS で検査周りの開発を担当しています。 最近は、私自身が基礎疾患持ちということもあり、社会情勢を考慮してフルリモートで業務に勤しんでいます。オンラインコミュニケーションは対面と比べ、意識しなければならない点が多く、慣れが必要であると日々感じています。少しでも対面に近い環境を実現するために、一眼レフカメラを Web カメラとして代用したり、ダイナミックマイクを使用してクリアな音声を届けられるように作業環境の改善に取り組んでいます。 今回は CLINICS 開発チームで課題となっていた「オンボーディングやキャッチアップに時間がかかる問題」を解決するために行った、横軸の取り組みについて紹介します。 はじめに CLINICS 開発チームではクラウド診療支援システム「 CLINICS 」の機能として主に電子カルテ、オンライン診療、予約システムなどの機能の開発を行っています。医療システムの開発において医療業務知識は必要不可欠であり、例えば「会計」や「検査」といった医療機関で行われる業務に関する理解が要求されます。そのため、各々が日々キャッチアップに勤しんでいる一方、ひとつひとつの業務が複雑であるために、複数の機能を横断したプロダクト理解、全体把握が難しい課題がありました。そこで、この問題を解決するべく「横軸勉強会」と題して、CLINICS のドメイン知識共有会を行うことにしました。 ドメイン知識共有会の概要 ドメイン知識共有会は各々が携わった中で蓄積してきた業務知識や開発の背景を共有する会です。本会は毎週 1 時間トピックに沿ってオンライン(Google Meet)で実施します。あらかじめトピック、発表者、ファシリテーターを指定し、発表者には簡単な資料を用意してもらいます。加えて参加者には以下のことを意識してもらいました。 発表者は対話型の発表を意識しフラットな雰囲気をつくる 参加者はチャットを用いて思ったことをつぶやく 各トピックは医療システムを開発する上で必要なドメイン知識を切り口として、技術寄りの内容となっています。発表者によっては勉強会後の宿題が用意されたり、おすすめの本紹介があったりと多種多様です。発表形式をあえて定めないことで、各回ごとに発表者の個性が出るというのも面白みの一つだと思います。特に宿題があった回では、後日にフィードバック会が設けられ知識の定着に繋がりました。 実際に行ったトピック 実際の様子 ドメイン知識共有会を終えて 今回ドメイン知識共有会を通して、機能の実装背景や概要を幅広く知ることができました。「会計業務の複雑さ」や「受付から診察までの動線設計」などのこれまでは共有する機会がなかった個々が持っている知識・知見を学ぶことができ、チーム全体でドメイン知識に関する認識合わせをする良い機会となりました。 最後に勉強会の振り返りを行ったところ、以下のような意見がありました。 ドメイン知識共有会を通してチーム力が上がってきている 勘違いしていた知識を訂正できた 相互理解が深まりチーム全体としてコミュニケーションのハードルを下げることができた 各専門領域に関するドキュメントを一箇所にまとめることができた ポジティブな意見が多く、取り組みの結果としてチームの基礎力向上にも繋がったと感じています。加えて、ドメイン知識共有会用に作成した資料はドキュメントとして残るため、オンボーディング資料などに活用ができそうです。しかしながら、以下のような問題もあります。 発表者の準備コストが高い 概要説明で終わってしまい即日業務で使用できる内容ではない 学んだことを深堀りできていないため知識の定着に繋がらない 上記については、例えば発表者を 2 人ペアにして準備コストを分散させたり、宿題を出して次回にフィードバックする、開発チーム以外も気軽に参加ができるようにライトなトピックを追加するなど、今後のドメイン知識共有会のなかで改善していきたいと思います。 さいごに 今回は CLINICS 開発チームで行った横軸の取り組みについて紹介させていただきました。 横軸でお互いをフォローしあうような「情報共有の場」を作ることで、より良い組織になっていくと感じています。今後、さらにプロダクトの機能が増えるとともに事業部全体として、関わるメンバーが増えるため、横軸での知識共有の仕組みは事業部を含めて必要であると考えています。開発チームに限らずに、プロダクトに関わるメンバーを巻き込み、組織コミュニケーションの改善を続けていきたいです。 最後までお読みいただきありがとうございました。 募集の一覧 | 株式会社メドレー メドレーの採用情報はこちらからご確認ください。 www.medley.jp

こんにちは、19 新卒の桶谷です。現在は CLINICS で検査周りの開発を担当しています。 最近は、私自身が基礎疾患持ちということもあり、社会情勢を考慮してフルリモートで業務に勤しんでいます。オンラインコミュニケーションは対面と比べ、意識しなければならない点が多く、慣れが必要であると日々感じています。少しでも対面に近い環境を実現するために、一眼レフカメラを Web カメラとして代用したり、ダイナミックマイクを使用してクリアな音声を届けられるように作業環境の改善に取り組んでいます。 今回は CLINICS 開発チームで課題となっていた「オンボーディングやキャッチアップに時間がかかる問題」を解決するために行った、横軸の取り組みについて紹介します。 はじめに CLINICS 開発チームではクラウド診療支援システム「 CLINICS 」の機能として主に電子カルテ、オンライン診療、予約システムなどの機能の開発を行っています。医療システムの開発において医療業務知識は必要不可欠であり、例えば「会計」や「検査」といった医療機関で行われる業務に関する理解が要求されます。そのため、各々が日々キャッチアップに勤しんでいる一方、ひとつひとつの業務が複雑であるために、複数の機能を横断したプロダクト理解、全体把握が難しい課題がありました。そこで、この問題を解決するべく「横軸勉強会」と題して、CLINICS のドメイン知識共有会を行うことにしました。 ドメイン知識共有会の概要 ドメイン知識共有会は各々が携わった中で蓄積してきた業務知識や開発の背景を共有する会です。本会は毎週 1 時間トピックに沿ってオンライン(Google Meet)で実施します。あらかじめトピック、発表者、ファシリテーターを指定し、発表者には簡単な資料を用意してもらいます。加えて参加者には以下のことを意識してもらいました。 発表者は対話型の発表を意識しフラットな雰囲気をつくる 参加者はチャットを用いて思ったことをつぶやく 各トピックは医療システムを開発する上で必要なドメイン知識を切り口として、技術寄りの内容となっています。発表者によっては勉強会後の宿題が用意されたり、おすすめの本紹介があったりと多種多様です。発表形式をあえて定めないことで、各回ごとに発表者の個性が出るというのも面白みの一つだと思います。特に宿題があった回では、後日にフィードバック会が設けられ知識の定着に繋がりました。 実際に行ったトピック 実際の様子 ドメイン知識共有会を終えて 今回ドメイン知識共有会を通して、機能の実装背景や概要を幅広く知ることができました。「会計業務の複雑さ」や「受付から診察までの動線設計」などのこれまでは共有する機会がなかった個々が持っている知識・知見を学ぶことができ、チーム全体でドメイン知識に関する認識合わせをする良い機会となりました。 最後に勉強会の振り返りを行ったところ、以下のような意見がありました。 ドメイン知識共有会を通してチーム力が上がってきている 勘違いしていた知識を訂正できた 相互理解が深まりチーム全体としてコミュニケーションのハードルを下げることができた 各専門領域に関するドキュメントを一箇所にまとめることができた ポジティブな意見が多く、取り組みの結果としてチームの基礎力向上にも繋がったと感じています。加えて、ドメイン知識共有会用に作成した資料はドキュメントとして残るため、オンボーディング資料などに活用ができそうです。しかしながら、以下のような問題もあります。 発表者の準備コストが高い 概要説明で終わってしまい即日業務で使用できる内容ではない 学んだことを深堀りできていないため知識の定着に繋がらない 上記については、例えば発表者を 2 人ペアにして準備コストを分散させたり、宿題を出して次回にフィードバックする、開発チーム以外も気軽に参加ができるようにライトなトピックを追加するなど、今後のドメイン知識共有会のなかで改善していきたいと思います。 さいごに 今回は CLINICS 開発チームで行った横軸の取り組みについて紹介させていただきました。 横軸でお互いをフォローしあうような「情報共有の場」を作ることで、より良い組織になっていくと感じています。今後、さらにプロダクトの機能が増えるとともに事業部全体として、関わるメンバーが増えるため、横軸での知識共有の仕組みは事業部を含めて必要であると考えています。開発チームに限らずに、プロダクトに関わるメンバーを巻き込み、組織コミュニケーションの改善を続けていきたいです。 最後までお読みいただきありがとうございました。 募集の一覧 | 株式会社メドレー メドレーの採用情報はこちらからご確認ください。 www.medley.jp

こんにちは、19 新卒の桶谷です。現在は CLINICS で検査周りの開発を担当しています。 最近は、私自身が基礎疾患持ちということもあり、社会情勢を考慮してフルリモートで業務に勤しんでいます。オンラインコミュニケーションは対面と比べ、意識しなければならない点が多く、慣れが必要であると日々感じています。少しでも対面に近い環境を実現するために、一眼レフカメラを Web カメラとして代用したり、ダイナミックマイクを使用してクリアな音声を届けられるように作業環境の改善に取り組んでいます。 今回は CLINICS 開発チームで課題となっていた「オンボーディングやキャッチアップに時間がかかる問題」を解決するために行った、横軸の取り組みについて紹介します。 はじめに CLINICS 開発チームではクラウド診療支援システム「 CLINICS 」の機能として主に電子カルテ、オンライン診療、予約システムなどの機能の開発を行っています。医療システムの開発において医療業務知識は必要不可欠であり、例えば「会計」や「検査」といった医療機関で行われる業務に関する理解が要求されます。そのため、各々が日々キャッチアップに勤しんでいる一方、ひとつひとつの業務が複雑であるために、複数の機能を横断したプロダクト理解、全体把握が難しい課題がありました。そこで、この問題を解決するべく「横軸勉強会」と題して、CLINICS のドメイン知識共有会を行うことにしました。 ドメイン知識共有会の概要 ドメイン知識共有会は各々が携わった中で蓄積してきた業務知識や開発の背景を共有する会です。本会は毎週 1 時間トピックに沿ってオンライン(Google Meet)で実施します。あらかじめトピック、発表者、ファシリテーターを指定し、発表者には簡単な資料を用意してもらいます。加えて参加者には以下のことを意識してもらいました。 発表者は対話型の発表を意識しフラットな雰囲気をつくる 参加者はチャットを用いて思ったことをつぶやく 各トピックは医療システムを開発する上で必要なドメイン知識を切り口として、技術寄りの内容となっています。発表者によっては勉強会後の宿題が用意されたり、おすすめの本紹介があったりと多種多様です。発表形式をあえて定めないことで、各回ごとに発表者の個性が出るというのも面白みの一つだと思います。特に宿題があった回では、後日にフィードバック会が設けられ知識の定着に繋がりました。 実際に行ったトピック 実際の様子 ドメイン知識共有会を終えて 今回ドメイン知識共有会を通して、機能の実装背景や概要を幅広く知ることができました。「会計業務の複雑さ」や「受付から診察までの動線設計」などのこれまでは共有する機会がなかった個々が持っている知識・知見を学ぶことができ、チーム全体でドメイン知識に関する認識合わせをする良い機会となりました。 最後に勉強会の振り返りを行ったところ、以下のような意見がありました。 ドメイン知識共有会を通してチーム力が上がってきている 勘違いしていた知識を訂正できた 相互理解が深まりチーム全体としてコミュニケーションのハードルを下げることができた 各専門領域に関するドキュメントを一箇所にまとめることができた ポジティブな意見が多く、取り組みの結果としてチームの基礎力向上にも繋がったと感じています。加えて、ドメイン知識共有会用に作成した資料はドキュメントとして残るため、オンボーディング資料などに活用ができそうです。しかしながら、以下のような問題もあります。 発表者の準備コストが高い 概要説明で終わってしまい即日業務で使用できる内容ではない 学んだことを深堀りできていないため知識の定着に繋がらない 上記については、例えば発表者を 2 人ペアにして準備コストを分散させたり、宿題を出して次回にフィードバックする、開発チーム以外も気軽に参加ができるようにライトなトピックを追加するなど、今後のドメイン知識共有会のなかで改善していきたいと思います。 さいごに 今回は CLINICS 開発チームで行った横軸の取り組みについて紹介させていただきました。 横軸でお互いをフォローしあうような「情報共有の場」を作ることで、より良い組織になっていくと感じています。今後、さらにプロダクトの機能が増えるとともに事業部全体として、関わるメンバーが増えるため、横軸での知識共有の仕組みは事業部を含めて必要であると考えています。開発チームに限らずに、プロダクトに関わるメンバーを巻き込み、組織コミュニケーションの改善を続けていきたいです。 最後までお読みいただきありがとうございました。 募集の一覧 | 株式会社メドレー メドレーの採用情報はこちらからご確認ください。 www.medley.jp

株式会社メドレーのエンジニアの笹塚です。 主にジョブメドレーのインフラを担当しています。 直近では、コンテナ化されていなかった環境の移行などをしていました。 休日は主にゲームをやっています。今は、日本語版がリリースされたばかりの「レムナント：フロム・ジ・アッシュ」に夢中です。 今回は Terraform のテスト環境を、 Terraform Workspaces を使用して構築した事例を紹介します。 背景 ジョブメドレーにはいくつかのサービスがあり、Terraform によるコード化が進んでいるサービスと、Ansible、 itamae などで部分的にコード化はされているものの、Terraform の使用が遅れているサービスが混在しており、これらのサービスについても Terraform への移行を進めています。 Terraform への移行とあわせて、メンテナンスを担当するメンバーを増やす必要があるのですが 【作業担当】 Terraform のコードから、実際に稼働させる環境を作るのは慣れていても難しい。 【レビュワー】 Terraform のコードの差分だけで、内容をすぐに把握するのは難しい。 などの理由から、作業担当、レビュワーともにハードルが低いとは言えず、Terraform によるインフラの変更内容を事前に確認できる環境構築が必要だと感じるようになりました。 検討内容 事前に確認できる環境を作るにあたり、まず最初に検討したのは、各ステージのコードを共通化することでした。 ジョブメドレーの関連サービスでは、大きくわけて 3 つのステージで構成しています。 Sandbox(個人の検証用) → QA(リリース前の検証用) → Production この各ステージのコードを共通化できれば、Production には QA 環境までで確認済みのコードを apply することができます。 ですが、Sandbox 環境、QA 環境、Production 環境はそれぞれ似てはいるものの、全てが同じ構成ではありません。 Terraform の HCL では if 構文がない( resource の作成を count で制御することはできる) module 単位でのリソース作成の制御ができない(Terraform 0.13 から module でも count や for_each が可能になる ようです) などの制限があり、構造の差分をコードで吸収しにくく、共通化できたとしてもメンテナンス性を下げる可能性が高いです。 また、すでに Terraform でコード化されている状態からの移行作業も楽ではないでしょう。 そこで、ステージごとのコードを共通化するのではなく、 AWS Organizations で別アカウントを作り、各ステージのコードを試せる環境を作ることにしました。 <目標とする> Terraform のコードをプロダクションアカウントで実行する前に、テストアカウントで実行し、設定した内容を AWS マネジメントコンソール や AWS CLI で確認することできる。 テストアカウント上で設定を確認した後、プロダクションアカウントに同じコードを apply することができる。 コストを抑えるため、テストアカウント上のリソースは、確認が終了したら destory することができる。 <目標としない> テストアカウント上でサービスが稼働することは目標としない。 必要なデータセットの作成など用意するものが増えるので、目標には含めませんでした。 設定作業 必要な作業は大きくわけて 2 つです。 Terraform Workspaces の設定 アカウントごとに必要なコードの追加、修正 Terraform Workspaces の設定 Terraform と AWS provider の設定を変更することで、workspace を切り替えることができます。 以下が作業イメージです。 workspace の追加 $ terraform workspace new production $ terraform workspace list default * production Terraform の環境変更 terraform { required_version = "= 0.12.28" backend "s3" { bucket = "example-state" workspace_key_prefix = "workspace" dynamodb_table = "terraform-state-lock" key = "example.tfstate" region = "ap-northeast-1" profile = "production" } } provider "aws" { region = "ap-northeast-1" version = "= 2.70.0" profile = var. workspace_profile [ terraform . workspace ] } variable "workspace_profile" { type = map ( string ) default = { default = "test" production = "production" } } この例では、default workspace はテスト環境、Production を実際にサービスが稼働する環境のアカウントになるように設定しています。 それぞれ default は、aws config の test profile、Production は production profile を参照しています。 s3://example-state/example.tfstate がテスト環境、 s3://example-state/workspace/production/example.tfstate が、プロダクション環境の state ファイルになります。 Terraform のコード内からは、現在の workspace 名を terraform.workspace で参照することができます。 ここまでの設定で $ terraform workspace select [workspace 名] で workspace を切り替えることができるようになりました。 あとは、アカウントごとに必要な変更をしていきます。 アカウントをまたいだ共通のリソースの定義 全アカウントでユニークにする必要があるリソース(S3 bucket、DNS など)の場合は、名称の分岐処理が必要です。 テストアカウントでは、リソース名に prefix をつけて作成するようにしました。 # 定義 variable "example_bucket_name" { type = map ( string ) default = { default = "test-example-bucket" production = "example-bucket" } } # リソースでの参照時 resource "aws_s3_bucket" "example" { bucket = var. example_bucket_name [ terraform . workspace ] .. } テストアカウントで起動するインスタンスタイプや台数の変更 テストアカウントでは EC2 のインスタンスを起動させなくても良い場合には、台数を変更するようにしました。 resource "aws_autoscaling_group" "example_web" { name = "example-web" max_size = 12 min_size = 6 desired_capacity = terraform. workspace == "production" ? 6 : 0 … } インスタンスの起動が必要な場合も、同様の分岐でインスタンスタイプの変更を行っています。 コード化をしないリソースの扱い プロダクションアカウントで一旦コード化を保留したリソースについては data source で参照しますが、テストアカウントにはリソースが存在しないため作成しなければいけません。 テストアカウントのリソースは確認が終了した段階で destroy したいので ステージ用の Terraform コードとは別に、必要なリソースを作成するコードを用意する 必要なリソース用のコード → ステージ用のコードの順に apply する ようにしました。 data source で参照できれば良い範囲でのコード化なので、この追加のリソースも最小限のコストになるようにしています。 以上の設定で、同じ Terraform のコードを workspace を切り替えて plan、apply ができるようになりました。 運用してみて プロダクションアカウントに apply する前に、テストアカウントで事前に apply することができるようになったので、作業中の試行錯誤もしやすくなりました。 レビュワーも、テストアカウント上で実際に apply された結果を確認することができるようになり、apply の差分だけではわかりにくかった変更内容を確認できるようになりました。 これなら新しく担当するメンバーの不安を、少しかもしれませんが解消できそうです。 まとめ 今回は Terraform のテスト環境を、Terraform Workspaces を使用して構築した事例を紹介させていただきました。 テストアカウント上のリソースの自動 destroy や、 plan、apply の自動化については触れられていませんが、また別の機会に紹介できればと思います。 長らく運用しているサービスでは、サービスを稼働させたまま解決しなければいけない課題が数多くあります。 それらの課題を、一つずつ着実に解決していくことに楽しさを見いだせる方、ぜひメドレーで一緒に働きましょう！ 募集の一覧 | 株式会社メドレー メドレーの採用情報はこちらからご確認ください。 www.medley.jp