「The Twelve-Factor App」を15項目に見直した「Beyond the Twelve-Factor App」を読んだ - kakakakakku blog
2012年に Heroku のエンジニアによって提唱された「The Twelve-Factor App」は素晴らしく，アプリケーションをうまく開発し，うまく運用するための「ベストプラクティス」として知られている．2020年になった現在でもよく引用されていると思う．日本語訳もある． 12factor.net Beyond the Twelve-Factor App とは？ クラウド化が進むなど，提唱された2012年と比較すると技術的な変化もあり，今までの「The Twelve-Factor App」で宣言されていた観点以外にも必要な観点やベストプラクティスがあるのでは？という意見もある．そこで，2016年に Pivotal のエンジニアが「Beyond the Twelve-Factor App」を提唱した．The Twelve-Factor App にあった「12項目をアップデート」し，新
OpenAPI Generator で API Client と型を自動生成した話 - BASEプロダクトチームブログ
フロントエンドエンジニアの @rry です。 自分は BASE の Sales Promotion というチームで主に新規機能開発を行っています。このチームでは主にオーナーさんの使う管理画面に新しく機能追加をしています。 そこで、管理画面で使っている API Client と型を、OpenAPI Generator を使って自動生成するようにしてみたのでそのお話を書きたいと思います。 そもそも OpenAPI とは？ https://www.openapis.org/ OpenAPI とは、RESTful Web サービスを記述、生成、使用、および視覚化するための仕様です。 ※ 以前は OpenAPI ではなく仕様自体も Swagger と呼ばれていましたが、現在は仕様自体については OpneAPI と呼ばれており、Swagger というのは OpenAPI を使ったツール群のことをさすよ
OpenAPI Specification ドリブンな開発事例とそれを支えるツール - NTT Communications Engineers' Blog
これは NTT Communications Advent Calendar 2021 3日目の記事です。 こんにちは、イノベーションセンターの松田 (@take4mats) です。 当社の Smart Data Platform (SDPF) のサービスラインナップの多くは、お客さまがサービスご利用に必要な操作を統一的に行うための Web UI に加え、同等の Web API を提供しています。 API 仕様は Knowledge Center にてサービスごとに一般公開されているのをご存知でしょうか？ (Knowledge Center で各サービス内の APIリファレンス のページをご覧ください。例えば こちらのリンク) この一般公開されている API 仕様はサービス開発初期に作成され、開発期間にも重要な役割を果たしています。 本記事では、その中で私が携わったサービスから、 API
Cloud Functions をローカル環境で統合テスト可能にした話 | BLOG - DeNA Engineering
はじめまして。AIシステム部MLエンジニアリンググループ で学生インターンをしている 早坂( @takemioIO ) です。 普段はパケット処理などをやっているのですが、縁あってここでは MLOps の通常業務に携わっております。 私は二ヶ月間インターンとして開発に取り組んでいました。ここではその実装物の一つを紹介します。 この AI システム部 のとあるプロジェクトでは、 Cloud Functions と Cloud Pub/Sub を利用したデータパイプライン を構築しております。 そのプロジェクトは毎日のように変更が取り込まれ、非常に開発が盛んですが一方それゆえに破壊的な変更で足を撃ち抜いてしまいそれによって悩まされることがありました。 さらにはクラウドサービスを利用してるという部分からローカルでの検証環境がありませんでしたので、毎回 GCP に デプロイするしかなく、トライアン
こんにちは Mirrativ CTOの夏です。 現在、ミラティブでは事業部単位でチームや目標を管理しており、エンジニアが所属するチームとして以下の6つがあります。今回はこのうち、エンジニアチームについて、2019年度に行ってきた取り組みの振り返りをしたいと思います。 ライブプラットフォームチーム ユーザの定着を追う マーケ連携チーム ユーザの新規獲得を追う エモモチーム 3Dアバターであるエモモを使った新体験の創出・基礎体験の向上を追う ストリーミング改善チーム モバイル端末でのライブストリーミングの配信・視聴の品質改善を追う インフラチーム クラウド上での安定したインフラ基盤の設計・構築を追う エンジニアチーム お問い合わせ調査、不具合・障害の再発防止、開発体験の向上を追う AI技術部 コミュニティやストリーミングとAI活用の可能性を追う 毎週定例で振り返りを行っており、Confluen
TypeScriptの型定義からJSON Schemaを生成するオンラインツールを作ってみた - Qiita
先日、TypeScript + Tynderから始める宣言的検証生活の記事にて スキーマ検証ライブラリTynderを紹介いたしました。 Tynderとは Tynderは、TypeScriptのサブセット＋独自の拡張文法から成るDSLによって 型の検査 単独の項目の必須・値の長さ・範囲や文字列パターンの検証 複数項目の相関や整合性検証の一部 (Union typeによる) を宣言的に行うことができます。 今回はTynderのスキーマ変換機能を使用して JSON Schema、GraphQL、Protobuf3 のスキーマを生成するオンラインツールを公開しました。 (GraphQL、Protobuf3については実験的機能です) TypeScript (Tynder DSL) → JSON Schema | GraphQL | Protobuf Converter Convert schema
チームの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とも呼ばれています
こんにちは。バックエンドエンジニアの岡本です。 ネットショップ作成サービス「BASE」の新規機能開発や既存機能の改修・運用を担当するShop Groupに所属しています。 今回は私が入社後初めてアサインされたプロジェクトであるメールマガジンApp（※）のアップデートを通して経験したこと・考えたことをバックエンドエンジニアの視点から振り返っていこうと思います。 ※ネットショップ作成サービス「BASE」の拡張機能であるBASE Appsの機能の一つ プロジェクトメンバー構成 ・プロジェクトマネージャー ・デザイナー ・フロントエンドエンジニア ・バックエンドエンジニア(私) メールマガジンAppアップデートの場合、上記4つの役割に対して1人ずつメンバーがアサインされました。1人ずつと言ってもそれぞれの担当を全て1人でやるということではなく、入社間もないメンバーにはメンターがアサインされるなどフ
背景 転職してサーバサイドエンジニアとして、RESTfulなWebAPIドキュメント書く機会が増えた。 RESTの歴史はそれなりに長いため、仕様書の書き方にもベストプラクティスが確立されている。 なので、今更感もあるが、せっかくなのでまとめてみようと思う。 心構え 出来の良いAPI仕様書をマネすること ユーザの対象を意識すること（社内利用か社外利用など。仕様書で意識するポイントが変わるため） トリッキーな使い方をするエンドポイントは疑う 最低限記載すること 共通項目 ドキュメントのメタ情報（バージョン、更新日付など） 常に必要なパラメータ（認証系） 流入制限 エンドポイント（URI） HTTPメソッド（GET、POST、PUT、DELETE、HEAD、OPTIONS、TRACE、CONNECT） Description（概要） Notes（備考） リクエストについて パラメータ（クエリパラ
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
Python+Flask+Blueprintを使ったAPIサーバ構築 ① 〜構成とサンプルプログラム編〜｜【MENTA】No1.メンターサービスでプロに直接相談しよう！
はじめに バックエンドのAPIサーバとして、Python + Flask + Blueprintの構成のサンプルプログラムを共有します。 Flaskというのは、Pythonで提供されるWebフレームワークです。 Blueprintは、Flaskの中で使われる部品で、アプリを分割することができ、プログラムの保守性を向上させることができるライブラリです。 本記事では、Python + Flask + Blueprintという構成で、テスト環境と本番環境の切り替えがしやすく、モジュールの分割もされ運用しやすい構成をするにはどうすれば良いか、サンプロプログラムを提供することで共有します。 環境 本記事では、以下の環境で動作確認を行いました。 Mac OSX Mojave（10.14.3） Python 3.7.2 Flask==1.0.2 Flask-API==1.1 Flask-Cors==3.
REST API 自動テストツールまとめ - Qiita
REST API のテストを自動化するためのツールを調査した結果のまとめです。 前提として、無料で使用可能なツールのみを対象としています。 分類 一口に REST API のテスト自動化といっても、様々な種類のツールがあります。 今回は独自に分類した以下の 4 種類を順に紹介していきます。 OpenAPI (Swagger) 連携系 GUI 系 CLI 系 CDC testing 系 OpenAPI (Swagger) 連携系 REST API の管理として OpenAPI (Swagger) で仕様を記述することは少なくないでしょう。 OpenAPI 連携系の API 自動テストツールでは、OpenAPI の仕様書をもとに自動テストが実施可能です。 Dredd GitHub - Dredd Star 3.2K もともと API Blueprint のテストツールだったようですが、Open
GitHub Trending RSS
GitHub Trending RSS Star The latest build: 7 October, 2023 All Languages Unknown Languages Unknown languages 1C Enterprise 2-Dimensional Array 4D ABAP ABAP CDS ABNF ActionScript Ada Adblock Filter List Adobe Font Metrics Agda AGS Script AIDL AL Alloy Alpine Abuild Altium Designer AMPL AngelScript Ant Build System Antlers ANTLR ApacheConf Apex API Blueprint APL Apollo Guidance Computer AppleScript
動的生成されたドキュメントをPRに添付した完成形はじめにこんにちは、株式会社スタディスト 開発部Webグループの笹木です。 今回は、circleci 上で生成したAPIドキュメント及び、静的ビルドしたStorybook をAWS S3 にアップロード後、プルリクのコミットステータスにそのリンクを添付するという仕組みを導入してみました。 背景弊社が開発、運用しているTeachme Biz の開発では、APIドキュメントの作成にapi blueprint 及び aglio を用いており、HTMLファイルに出力して配布しています。 また、フロントエンドのコンポーネントカタログとして、Storybook を採用しており、こちらは各開発者が開発環境上で立ち上げて利用するというケースが多いです。 これまでの問題点上記のドキュメントを、従来は開発者が個々人でビルドし、フロントエンド開発に活用したり、それ
Webでも組み込みでも、何かのシステムを構築したことがある方ならご存知でしょう。 開発というものは、「プログラムを書く作業」よりも、その前の「仕様を決めて文書化する作業」の方がずっとカロリーが高いものです。 最近ちょっとしたAPIを作る機会があり、やはりAPI仕様設計のしんどさと闘いました。 が、API Blueprintという規格とそれに対応するツールを使うことで、そのしんどさが相当な具合で和らぐことがわかりました。 今回はこのAPI Blueprintを全力で推していく記事です。 API Blueprintとは？ https://apiblueprint.org/ API Blueprintは、APIの仕様設計や連携開発を効率的に進めるためのドキュメント仕様です。 Markdownに従った仕様になっているので、そのまま眺めてもある程度理解できるのですが、Blueprintの強みはなんと
背景 今やWebだけでなく、iOS、Android、TV、カーナビといった多数のクライアントでAPIを利用する時代です。 各クライアントでBFFを置く設計もありますが、開発コストや運用コストを考えて同一のAPIサーバを用意し利用することも多いと思われます。 加えてサービスが大きくなってくると外部企業との連携や有志の開発者のためにAPIを公開するケースもあります。 そういった状況下では単にドキュメントベースでやり取りするのは難しく、しばしばAPIとドキュメントの乖離が生まれ負債となっていきます。 そのためこれらの問題を解決できる JSON Schema Protocol Buffers OpenAPI Specification といったスキーマ言語の活用がとても重要になってきます。 今回はOpenAPIについて話します。 他のスキーマ言語の問題点は？ まずOpenAPI以外のスキーマ言語で
しばらく書いてなかったけどメモ程度に dreddとは dreddはopenapi(swagger)やAPI Blueprintの定義を読み込んでテストを実行してくれる便利なツールです。 例えば localhost:8080 でAPIサーバを動かして のようにすればschema.yamlに定義されたAPIの定義に従ってリクエストを送り、レスポンスが仕様に従っているかテストしてくれます。 が、ログインしてtokenを貰ってそのtokenでアクセスするというようなAPIはそのままではテストできません。 hooksという仕組みを使うと、レスポンスからtokenを取得して以後はそれを使う、といった動作が可能になります。 dredd hooks ドキュメントにある通り、hooksは様々な言語で書くことができますが、とりあえずdreddと同じnode.jsでやってみます。 （なぜかと言うと、docker
はじめに フロントサイドとサーバーサイドのエンジニアが、分業する際に大事なものはなんでしょうか。 コンポーネントの切り方の認識合わせ？？そうかもしれません。 それと同様に大切なのが、API仕様の共有の仕方だと思います。 今回、私たちのチームではサーバサイドのAPIの開発に先立ち、フロントサイドの開発をする箇所が出てきたため、 Open API仕様記述ツールを投入して仕様共有してみることとしました。 そもそもOpen API仕様って Open API仕様（OpenAPI-Specification）とは、一言で言ってしまえばREST APIを記述する為の仕様。yamlやjsonに近い形式で記述することができます。 GitHub - OAI/OpenAPI-Specification: The OpenAPI Specification Repository もともとSwaggerっていうフレ
ドキュメントちゃんと保守できてますか？ API開発とドキュメントの保守は切っても切れない問題です。 仕様の記述はもちろんのこと、サンプルを試せるAPIクライアントや、仕様に則った実装になっているかテストも自動化したいですよね。 本記事では、現在開発中のAPIアプリケーションで、実際に僕が試行錯誤していく中でたどり着いたベストプラクティスを紹介しようと思います。 アーキテクチャ iOSアプリのバックエンドとしてJSONを返すAPIサーバー Rails6 × MySQL5.7 on Docker いつもの というお買い物アプリです。 ドキュメント何で書いてますか？ Excel => つらい Markdown => つらい 何らかのDSLを用いて生成するツール => 素でマークダウンを書くのはつらみが深いので何かしらツールを使いましょう。 apiary, api blueprint, APIDO
こんにちは。CTOの河内です。 多くのプロジェクトがスタート時はそうである通り、我々のプロジェクトもAPI仕様がありませんでした。 最初は規模が小さく問題として認識されていなかったのですが、規模が大きくなり、また開発者の入れ替わりを経験するごとに、「この API って何返してくるの？」という問いに答えられる人が段々といなくなってきました。 「ソースが仕様だ」とサーバの実装を読めばもちろん答えられるのですが、ソースコードを読み解く時間がかかるため効率的ではありません。 また、サーバ実装が唯一の情報源となるため、ロジックが何かおかしいと感じても、それが仕様なのかバグなのか判断できない状態でした。 API仕様を先に定義し、通信上の疑問にはAPI仕様で答えられるようにしたかったのです。 これは一般的な課題で、日本CTO協会が2019年12月に公開した DX Criteria DX Criteria
こんにちは、データAI部でPythonエンジニアをしている平田(@JesseTetsuya)です。普段は、PoCとデータをもってくる、というところ以外全部やる、というスタンスで開発業務を行っています。 日頃は、Flask1.1.4を利用していましたが、2021年5月11日にFlask2.0へのメジャーバージョンアップがありました。 メジャーバージョンアップということもあり、多くのアップデート項目がありました。そこで、特に日頃の業務に関わりそうなアップデートについて当記事にまとめていこうと思います。 Flaskとは？ Flaskは、PythonistaのArmin Ronachertによって2010年に初回リリースされました。いまでは、 Armin Ronacherを筆頭にPalletプロジェクトと言う名前でFlaskを含む、Flaskに関連する各ライブラリのメンテナンスがPalletプロジ
[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)
はじめに 最近WebAPIを触る機会があって懐かしくなったので、以前とある案件でかじったAPI Blueprintでも布教してみます。 APIの仕様をMarkdown拡張記法で記述できる言語です。 慣れるまでは正直書きづらいですが、元がMarkdownなのでSwaggerに比べるとまだ書きやすい方だと思います。 今度記事にしますが、先日Frisby.jsというWebAPIのテスティングフレームワークを触るためにJWT認証を使った簡単なWebAPIを作ったので、サンプルとしてAPI Blueprintで仕様書を書いてみました。 FORMAT: 1A HOST: http://localhost/api # Sample API Frisbyを触ってみるために最低限の機能だけで作ったWebAPI ## ユーザ登録 [POST /users] 新規ユーザを登録する + Request (appl
最近は API Blueprint で仕様書を書くことが多かったのですが、Swagger が世界標準になるかもしれない、ということもあり、開発の効率化を進めるためにも概要をまとめてみようと思った次第です。 Swaggerとは Swagger は RESTful APIを構築するためのオープンソースのフレームワークのことです。「Open API Initiative」という団体がRESTful APIのインターフェイスの記述をするための標準フォーマットを推進していて、その標準フォーマットがSwaggerです。Swaggerには多くの便利なツールが提供されていることもあり、多くのメリットを享受できそうです。 Swagger Spec を書いておけば自動的にドキュメント生成までしてくれ、それだけではなく、ドキュメントから実際のリクエストを投げられる優れものです。 Swaggerのツール群 ツール
週刊Railsウォッチ（20200210前編）Railsのベンチマークジェネレータ、長いバックグラウンドジョブと戦う、Timestamp切り詰めの謎、Open APIツールほか｜TechRacho by BPS株式会社
2020.02.10 週刊Railsウォッチ（20200210前編）Railsのベンチマークジェネレータ、長いバックグラウンドジョブと戦う、Timestamp切り詰めの謎、Open APIツールほか こんにちは、hachi8833です。そういえば明日は祝日ですね。コロナウイルス流行の様子が早速ビジュアライズされたようです。 元記事: コロナウイルスの黙示録的な広がりをリアルタイムで追跡するサイトが公開 | ナゾロジー 「まあこれで何かわかったとしても自分らに打てる手は限られてますし😷」「情報の動き激しくて...😅」（以下延々） 参考: CNN.co.jp : 新型ウイルス、潜伏期間中の感染例は「誤り」 独当局 各記事冒頭には⚓でパーマリンクを置いてあります: 社内やTwitterでの議論などにどうぞ 「つっつきボイス」はRailsウォッチ公開前ドラフトを（鍋のように）社内有志でつっつい
from flask import Blueprint, request, abort, jsonify from models import db, User # api Blueprint作成 http://host/api 以下のものはここのルールで処理される api = Blueprint('api', __name__, url_prefix='/api') # エンドポイント http:/host/api/users, GETメソッドのみ受け付ける # routeは複数指定も可能、methodsはリストなので複数指定可能 @api.route('/users', methods=['GET']) def list_user(): # クエリーパラメータ取得 request.args.get # 第一引数:パラメータ名、default=で初期値、type=で変換する型を指定できる
はじめに こんにちは！株式会社80&Companyの技術広報です。 弊社の開発部署では毎週火曜日の朝9:30から社内勉強会を行なっています。 今回の記事は社内のエンジニアがフロントエンド業務を担当していた際に、API周りの作業改善のため、スキーマ駆動開発の導入提案を社内勉強会で発表したものを紹介します。 スキーマ駆動開発を検討中の方は参考にしてみて下さい♪ 読者の対象 スキーマ駆動開発に興味がある方 スキーマ駆動開発の導入を検討している方 スキーマ駆動開発とは スキーマ駆動開発とはAPIのスキーマを最初に定義して、定義をもとにバックエンドやフロントエンドの開発を進める開発手法です。はじめにAPIのスキーマ定義をするため、フロント <-> バックエンド間におけるAPI仕様のずれを防ぐことができます。API仕様に変更を行う時も、API仕様書を変更してフロントエンド、バックエンドそれぞれの開発を
以前API BlueprintでAPI仕様書を書くという記事を書いた。 あれからまぁまぁ経ったがAPI Blueprintの先行きは暗い。 仕様もツールも進化せず最新のnodeでは動かないものまででている。 さすがに困ったので、 swaggerを使うことにしたのだが、 こちらも何か良くなったのかと言えば、 現状も変わってないようだ。 (-_-;) めんどい YAML直接編集で仕様書書くとかやってられないし、 swagger editorも使い勝手が最悪だし。 何か良い方法はないかと探したら良いものがあった。 Stoplight Studio APIテストのGUIで仕様書を出力するツール。 これならまだ使えそうか。 ソースはGithubで管理しているので、 ドキュメントはmarkdownにしたい。 あと、見やすさを重視してHTML表示もしたい。 そのあたりもカバーしよう。 ヾ(・ω<)ﾉ"
j次のブックマーク
k前のブックマーク
lあとで読む
eコメント一覧を開く
oページを開く
ミラティブ エンジニアチーム四季報（創刊号） - Mirrativ Tech Blog
バックエンドエンジニアから見たプロジェクトの軌跡 - BASEプロダクトチームブログ
APIドキュメントの書き方をまとめてみる - あらにわ
OpenAPI関連のサイト・ツールまとめ | GiFT（ギフト）株式会社
CircleCIとS3とGithub API を用いて、プルリクごとのドキュメントを共有しよう
API Blueprintで仕様書を作成しつつモックサーバも起動する手順 | MONSTER DIVE
OpenAPI で REST API のスキーマ作成 - Carpe Diem
dreddで認証付きのAPIをテストする - Qiita
Open API仕様記述ツールを比較してみた - Qiita
ぼくのかんがえたさいきょうのAPIドキュメント運用🤹♀️ - Qiita
独自の外部 DSL 編集をエディタでサポートする - FLINTERS Engineer's Blog
Flask 2.0.xのアップデート項目紹介 - Classi開発者ブログ
API Blueprintのススメ - Qiita
Swaggerの概要をまとめてみた。 - Qiita
Flask REST API サンプル - Qiita
スキーマ駆動開発 with Open API - Qiita
SwaggerでOpenAPI仕様書を作成、HTMLやMarkdownに変換する