APIの開発は複雑でコストがかかる可能性があり、頻繁に更新されることからドキュメントを整備するのも難しい。APIの設計、開発、ドキュメントの整備、管理にまつわる課題と効率さの問題に対処するアプローチが、RESTful API Modeling Language（RAML：RESTful APIモデリング言語）だ。 RAMLコードを使えば、開発者はAPIの動作を説明する仕様を策定してからそのAPIをデプロイするまでのAPIライフサイクルを管理することができる。 RAMLとは RAMLは、RESTful APIを記述することを目的とするオープンソースの記述言語だ。2013年、米国のIT自動化および統合ベンダーであるMuleSoftを中心とする数社の企業によって作成されたRAMLはAPIの開発に大きな役割を果たしてきた。2018年、MuleSoftはSalesforceによって買収され、RAML
Tesla API が触りたいけれど、車が高くて買えないので、Tesla API の Mock API Server を作って、擬似的に Tesla を所有している感覚を API で体験する - Morning Girl
Tesla ご存知ですか？ そう、あの Tesla です。最近日本でも Model 3が出始めて、人気沸騰中（だと個人的に思っている）の電気自動車のことです。 https://www.tesla.com/ja_jp この Tesla なんですが、iPhone と Android 向けのアプリを提供していて、このアプリから車の情報を確認したり、温度調整やロックの解除など、色んな Tesla の操作を行えるようになっています。 https://apps.apple.com/jp/app/tesla/id582007913 【機能一覧】 充電状況をリアルタイムで確認し、充電を開始または停止する 運転前に車両の暖房/冷房を入れる (ガレージ内でも可能) 遠隔からロックまたはロック解除する 車の現在地を確認したり、動きを追跡する お気に入りのアプリから目的地を送信し、ナビを開始します 同乗者はすばや
尺貨マン on Twitter: "編成写真の難しさを図解。以前のツイートに皆様のご意見を加えた改訂版となります。 https://t.co/w91RAmL7ix"
編成写真の難しさを図解。以前のツイートに皆様のご意見を加えた改訂版となります。 https://t.co/w91RAmL7ix
チームのWeb API開発を最適化するSchema Driven Developmentの解説＆実装例 - Qiita
チームでのWeb API開発において、進行を妨げる要因は様々な形で噴出します。 「フロントはバックエンドのAPI実装待ちなので動けません...」「ドキュメンテーションのコストが重い...」「ドキュメントと実装が全然違うので参考にならない...」 また、APIスキーマ設定が不十分だと、ビジネスドメインの最低原則やクライアント側のニーズを理解せずに、バックエンド都合のAPIがそのまま実装される危険性もあります。 そうした問題を解決すべくSchema Driven Developmentと呼ばれる開発手法が生まれました。 Schema Driven Developmentとは？ Schema Driven Development(以下SDD)とはチームにおけるWeb API開発フローを改善する開発手法の一つです。スキーマ駆動開発やSchema First Developmentとも呼ばれています
OpenAPI関連のサイト・ツールまとめ2020.10.29 OpenAPI関連のサイトやツールなどの情報が種々雑多にあるので、自分の中での整理と忘備録として残すためにまとめました。（2020年10月時点） 概要OpenAPIとはOpenAPIという表現が使われた場合、恐らくそれらの多くはOpenAPI Specification（以下OAS）に基づいてJSONやYAMLで記述されたREST APIの仕様書（スキーマ）を指しているように思います。 OASはREST APIの仕様を記述するための規格であり、それ自体がなにかのツールやサービスを提供するものではありません。 とはいえ関連するツールやサービスも普及してきているので、あまり言葉の意味を気にしすぎる必要もないかもしれませんが。 OpenAPI Specification (v3.0.3)Implementer’s Draft (OAS
Webでも組み込みでも、何かのシステムを構築したことがある方ならご存知でしょう。 開発というものは、「プログラムを書く作業」よりも、その前の「仕様を決めて文書化する作業」の方がずっとカロリーが高いものです。 最近ちょっとしたAPIを作る機会があり、やはりAPI仕様設計のしんどさと闘いました。 が、API Blueprintという規格とそれに対応するツールを使うことで、そのしんどさが相当な具合で和らぐことがわかりました。 今回はこのAPI Blueprintを全力で推していく記事です。 API Blueprintとは？ https://apiblueprint.org/ API Blueprintは、APIの仕様設計や連携開発を効率的に進めるためのドキュメント仕様です。 Markdownに従った仕様になっているので、そのまま眺めてもある程度理解できるのですが、Blueprintの強みはなんと
ソフトウェアプロジェクトではREADMEファイルがプロジェクトコードへの入り口となるため、極めて重要だ。 READMEファイルとは、ソフトウェアプロジェクトを紹介および説明するテキストファイルまたはマークダウンファイルを指す。このファイルには、ユーザーや開発の関係者がプロジェクトを理解して作業するのに必要な情報を含める必要がある。 READMEファイルが対象とする範囲や説明する内容は、関係するプロジェクト、ユーザー、開発チームごとに異なる。それでも、全てのREADMEのファイルに記載すべき基本要素はある。プロジェクトと関係者にとって最適な方法で、記載すべき基本要素を盛り込んだREADMEファイルの作成方法を習得することが開発者にとって重要になる。 READMEファイルの作成方法 関連記事 アジャイル環境で必須 ビジネス要件定義書（BRD）を作成する際のポイント アジャイルソフトウェアチーム
背景 今やWebだけでなく、iOS、Android、TV、カーナビといった多数のクライアントでAPIを利用する時代です。 各クライアントでBFFを置く設計もありますが、開発コストや運用コストを考えて同一のAPIサーバを用意し利用することも多いと思われます。 加えてサービスが大きくなってくると外部企業との連携や有志の開発者のためにAPIを公開するケースもあります。 そういった状況下では単にドキュメントベースでやり取りするのは難しく、しばしばAPIとドキュメントの乖離が生まれ負債となっていきます。 そのためこれらの問題を解決できる JSON Schema Protocol Buffers OpenAPI Specification といったスキーマ言語の活用がとても重要になってきます。 今回はOpenAPIについて話します。 他のスキーマ言語の問題点は？ まずOpenAPI以外のスキーマ言語で
はじめに フロントサイドとサーバーサイドのエンジニアが、分業する際に大事なものはなんでしょうか。 コンポーネントの切り方の認識合わせ？？そうかもしれません。 それと同様に大切なのが、API仕様の共有の仕方だと思います。 今回、私たちのチームではサーバサイドのAPIの開発に先立ち、フロントサイドの開発をする箇所が出てきたため、 Open API仕様記述ツールを投入して仕様共有してみることとしました。 そもそもOpen API仕様って Open API仕様（OpenAPI-Specification）とは、一言で言ってしまえばREST APIを記述する為の仕様。yamlやjsonに近い形式で記述することができます。 GitHub - OAI/OpenAPI-Specification: The OpenAPI Specification Repository もともとSwaggerっていうフレ
こんにちは。CTOの河内です。 多くのプロジェクトがスタート時はそうである通り、我々のプロジェクトもAPI仕様がありませんでした。 最初は規模が小さく問題として認識されていなかったのですが、規模が大きくなり、また開発者の入れ替わりを経験するごとに、「この API って何返してくるの？」という問いに答えられる人が段々といなくなってきました。 「ソースが仕様だ」とサーバの実装を読めばもちろん答えられるのですが、ソースコードを読み解く時間がかかるため効率的ではありません。 また、サーバ実装が唯一の情報源となるため、ロジックが何かおかしいと感じても、それが仕様なのかバグなのか判断できない状態でした。 API仕様を先に定義し、通信上の疑問にはAPI仕様で答えられるようにしたかったのです。 これは一般的な課題で、日本CTO協会が2019年12月に公開した DX Criteria DX Criteria
RGAでインフラエンジニアをしている川合です。 以前SHIFT EVOLVEでOpenAPIについて発表したのですが、この時はライトニングトークだったということで持ち時間も少なく、あまり詳しくは話すことができなかったので、以下の2点についてここで少し詳しく書いておこうと思います。 OpenAPIというものはなにかの概要解説 OpenAPIを用いた開発手法について簡単な説明 ※元のスライドはこちらをご参照ください。 https://speakerdeck.com/shift_evolve/apihuasutofalsekai-fa ※コードはこちらにありますので合わせご参照ください。 https://github.com/kwryoh/oapi-sample OpenAPI とはOpenAPIはRESTful API記述方法のひとつです。 APIの各パスやリクエスト・レスポンスの形式の仕様を
Postmanとは Postmanの使い方を解説する前に、そもそもPostmanについて軽く概要を説明します。 Postmanとは、APIを開発・テストするときには欠かせないツールです。 Postmanには API client（APIクライアント）：HTTPリクエストを設定して、テストを簡単に行うことができる API design（API設計）：OpenAPI、RAML、GraphQL、またはSOAPフォーマットを使用してAPI仕様を設計できる API documentation（APIドキュメント）：自動でAPIのドキュメントを生成できる API testing（APIテスト）：APIのテストを自動化して実行できる Mock servers（モックサーバー）：APIのリクエストを送れない場合に使う。APIエンドポイントをシミュレートができる Monitors（モニター）：APIのパフォ
[GitHub] Markdownの「シンタックスハイライト」に対応している言語一覧 - ねこの足跡R
Markdownでプログラムのソースコードを記述する場合に使うバッククォート3つで囲う「コードブロック」ですが、気の利いた環境だと自動的にシンタックスハイライトによって予約語やコメント分などを色分けして見やすく表示してくれます。 GitHubも例外ではなく、各リポジトリに常設されているWikiやREADMEなどをMarkdownで記述した場合は自動的にシンタックスハイライトされます。 メジャーな言語であればそのまま記述すればよいのですが、例えばYAMLやJSONなどのデータ形式や、Apacheの設定ファイルなどそもそもカラーシンタックスに対応しているのか、対応している場合キーワードはなんだろうと迷いますよね。 今回はGitHubが対応しているカラーシンタックスの設定一覧をまとめておきます。 ハイライトのやり方 GitHubで利用できる言語一覧 定義 一覧 おまけ 抽出方法 参考ページ ハイ
![[GitHub] Markdownの「シンタックスハイライト」に対応している言語一覧 - ねこの足跡R](https://cdn-ak-scissors.b.st-hatena.com/image/square/e5bf125aecc59cdb944df8797e85524099779984/height=288;version=1;width=512/https%3A%2F%2Fogimage.blog.st-hatena.com%2F820878482973262145%2F6801883189061409297%2F1701758116)
Welcome to a new series of posts that will take you on a visual journey through the OpenAPI Specification (OAS) and its tooling ecosystem! Why diagram the OAS ecosystem? As part of the efforts to design OAS 3.2 and 4.0 “Moonwalk”, I wanted to figure out how different sorts of tools work with the OAS. Moonwalk is an opportunity to re-think everything, and I want that re-thinking to make it easier t
j次のブックマーク
k前のブックマーク
lあとで読む
eコメント一覧を開く
oページを開く
RESTful APIの設計、開発、ドキュメント管理を手助けする「RAML」とは
OpenAPI関連のサイト・ツールまとめ | GiFT（ギフト）株式会社
API Blueprintで仕様書を作成しつつモックサーバも起動する手順 | MONSTER DIVE
READMEファイルに何を書くべき？ ベストプラクティスを紹介
OpenAPI で REST API のスキーマ作成 - Carpe Diem
Open API仕様記述ツールを比較してみた - Qiita
独自の外部 DSL 編集をエディタでサポートする - FLINTERS Engineer's Blog
OpenAPI（APIドキュメント）を用いたGoのAPIサーバー開発｜SHIFT Group 技術ブログ
【Postman】基本的な使い方を解説します
Analyzing the OpenAPI Tooling Ecosystem