先請主席致詞。

我是唐鳳，叫我唐鳳就好了。今天其實因為許多朋友們在場，有許多技術上的問題，如果用打字或者是寫的比較方便，可以用手機連到slido.com，我用臺灣大收訊滿好的，但據說某些特定的電信商的收訊不是很好，這邊有iTaiwan，想辦法上了網路之後，到了slido.com，輸入00623，就會進入一個匿名的聊天室，我之前開這一類的協調會議，會發現有些朋友們在匿名的情況下會問具體的問題，我們在具體的問題上，其實這個就是接下來需要跟其他人說明的時候，越具體的東西越早提出來，越不會在後面滅火的情況，因此我會跟大家說不用特別管職位，已經有人說「Hello大家好」了，可以進入這樣的平台，我會隨時把意見投影在上面，裡面有一個具體收攏的時間及回答。

如果看到提的問題或想法自己也想提的話，可以按讚就好了，按讚越多就會浮到越上面，大概有二十個人按同一個問題讚，我如果先回覆，就會一次回二十個人的問題，這個是規則。這應該是比較不正統的主席致詞，但我的致詞就是這樣，請繼續。

我是國家發展委員會的承辦人，接下來就由我為各位介紹一下共通性應用程式規範的草案。

我先說明一下什麼是應用程式介面，這個名字有一點拗口，所以我之後會用「API」來簡稱，也就是應用程式介面。

簡單是從目的、應用反應及推動的規範準則。目的講白了非常簡單，也就是希望API更容易被使用，能夠更容易被調整或者是維護。先說明一下API在機關裡面常常拿來作什麼，可能被拿來作一些資料存取、資料交換之用，常常會發生一些狀況，也就是有些廠商可能開發出一個API，什麼東西都沒有留下，之後可能因為某些原因而沒有繼續得標或維護，而這一個API的功能就這樣消失。所以我們希望藉由共通性規範API的修訂，讓API的功能更容易被知道與使用。

        （簡報第4頁）這個是規範當中比較正式的文字，也就是為了擴大政府資訊服務效益，並且在保有各機關的API開發系統的彈性上，我們希望大家能夠follow OAI組織所訂出來的OAS（OpenAPI Specification）的標準，之前大家可能會聽到以OPI的規範，其實指的是這一個OAS的標準。

實質上的目的是，可以藉由一個一致性的描述方式，讓大家把API的說明文件提供機器可讀的標準格式，就藉由這一個方式來達成前面所說的目的。

我剛剛只有講到API的部分而已，其實跟大家想像的Open Data有一點脫鉤的，就是說並不是只適用於Open Data的範疇，而是所有採用API進行應用的範圍，通通都適用。

只要提供API說明文件的話，就能夠具有一定的共通性，讓API能夠透過某種方式都能夠理解API是什麼用途。我們在推動規範的時候，並不會受到限制，也就是API可能只是機關內部的資料介接，或者是有一些特別的存取限制什麼的，這個都不會影響規範的適用。按

重點在於API開發應該提供OAS標準的說明文件。

什麼叫做「API說明文件」，我相信這邊大部分都是資訊同仁，所以大家對這個應該都不會太陌生，也就是裡面充斥著很難製作的一些合併儲存格拼湊出來的Word文件，然後再轉成PDF。

用這樣的方式提供的話，其實對於開發者而言，也要重新看很長的文件才能理解這一個API要怎麼樣使用，就各個參數、功能什麼樣的型態存取。

（簡報第8頁）甚至有一些API的說明文件都沒有，我相信這個應該各位長官先進都知道這一種情況。

什麼是符合OAS標準的說明文件？其實看起來就像是一串程式碼一樣，有一個完整的架構。因為這邊是一個說明會的性質，所以暫時不贅述程式碼的部分，剛剛那個程式碼可以透過工具，變成具親和力，也就是非常容易理解的UI介面，而這一個UI介面不只是讓人容易理解這一份說明文件，這個範例是政府資料開放平台的介接規範，裡面可能就是簡單的五支API，不只看到API，還有看到介面下進行一些參數的操作，也就是這一份說明文件是可以直接參與互動的，而不是一份靜態的文件而已。

（簡報第11頁）我們剛剛講的右邊是傳統式的API說明文件，左邊是能夠符合OAS標準之後，透過工具轉化出來的結果，你覺得哪一個比較好用？我想大家應該都有答案吧！這個也是為什麼這一次共通性規範會做這樣的修訂，這個是大家希望能夠針對API的部分，去提供符合OAS標準的API說明文件。

也就是這一個規範的修正，並不是要求大家API要如何訂定，而是API的說明文件要符合OAS標準。

（簡報第13頁）其實規範準則的部分，大部分是沿用我們之前一個政府資料開放平台適用的叫做「共通性資料存取應用程式介面規範」，其實原本的適用範圍比較僅限於資料開放的範疇下，但是因為現在的範圍是整個擴大到一般適用的API，這邊會有輕便性、標準化都是原本的內容，而共通性的部分就是加註這一次的OAI的OAS標準。

符合OAS標準的說明文件，因為名字有一點長，所以我接下來就簡稱OAS文件，接下來會針對它的重點來說明。

（簡報第16頁）OAS文件基本上是由單一的檔案製成，也就是提供一個系統服務，裡面可能有七支、十支API，你可以在同一份文件裡面撰寫，而這份文件，我們會建議是JSON或YAML格式來呈現；這個部分大家不用緊張，因為我們規範後面都有提供範例、原文。

剛剛有一頁看起來很像程式碼那一頁，其實就是基於更物件，也就是OpenAPI Object，裡面每一個物件，其中的欄位跟屬性，有一點像物件繼承的概念，有一點像物件所構成的一份說明文件。

基本上只要follow我們提供的一個規範附件OAS標準，其實只要有一點程式底子的人都可以寫出這樣的文件。

那時在跟其他部會討論時，有一些部會很擔心的一點是，如果要請廠商或者是自己撰寫出一份API說明文件，要如何驗證這一份文件是否是合乎標準的？其實這個大家不用擔心，應該是說OAI組織本身就有提供官方的驗證工具，可以很簡單把撰寫出來的YAML或者JSON檔丟上網站，就會有驗證的結果，我們稍候都會有demo。

除了檢測通過以後，還有一個很重要的是，因為畢竟是一份API的說明文件，是否符合各機關的需求，還要由各機關去看我們這邊所提供的API功能是不是跟這一份說明文件是吻合的；如果既符合格式的測試，也符合機關專案需求的話，我們就會視為通過驗證。

（簡報第19頁）Swagger是OAS之前的版本，等於是OAS2.0版。這裡有一個網址，跟政府資料開放平台規範的測試（http://data.gov.tw/%E6%94%BF%E5%BA%9C%E8%B3%87%E6%96%99%E9%96%8B%E6%94%BE%E8%B7%A8%E5%B9%B3%E8%87%BA%E4%BB%8B%E6%8E%A5%E8%A6%8F%E7%AF%84_v2.0.yaml），這個是測試網站原本的樣子，我們把政府資料平台已經製作好的OAS文件之路徑在這裡，我們把這一個路徑放下來之後，就會在「政府資料開放跨平台介接規範」的網站貼上，就可以得到一個展示的結果。

也就是API裡面，像這個是資料集編號清單的功能（如網站），像裡面有一些回傳址的一些欄位或參數的描述，同時也可以進行測試，而測試的部分就可以直接輸入，像是正在呼叫這一些API一樣，可以丟入你所要的參數。

（簡報第19頁）這個同時是測試兼呈現的網站。

因為我們規範當中所描述的OAS部分是根據OAS3.0的部分描述，近期可能會做正式的釋出，目前還沒有正式工具可以使用，但已經一些第三方的工具可以參考，我們可以視自己的專案需求，決定採用之前或之後的版本，其實都有工具可以使用。

（簡報第21頁）接著是規範準則第二項，有關於RESTful API的立法規則，這個是舊規範，但是很簡單；什麼是RESTful API？其實就是一種API風格的設計，我想資訊人員應該都不至於太陌生，純粹是很簡單的型態、範例。

（簡報第23頁）API的版本描述，這個也是舊的，很單純在API的後面加上一個版本，然後後面還有一些名稱規範。

（簡報第25頁）在這一次規範的修正裡面，還有一項比較新的是API Discovery，這一項的功能是當各機關的系統可能有一部分API是可以提供外界直接查詢的，我們要如何提高這一些API的可識別程度？可以在這一個系統的目錄下去加APIs.json的文件，裡面可以加入這樣的敘述，這樣的敘述，別人就可以很容易得知這個網站裡面有提供哪一些API服務，就可以跟前面的OAS文件搭配，就可以知道你們提供的API，除了可以知道哪一些之外，也知道應該如何使用它。

（簡報第26頁）很快來到小結，其實有一個原則，也就是什麼樣的東西會需要適用這樣的規範？像建置、維護的API就適用這一個規範。再者，重點API的說明文件是需要符合OAS的標準。

另外，針對各個機關已經有建置的API，其實基本上是不需要進行調整，因為我們的規範要求是說明文件的程式化，應該說機器可讀化。

就像我們達成一開始的目的，也就是讓API更容易使用、維護跟調整，也可以避免A機關跟B機關資料介接，特別去開發一個介接的方式，然後C機關跟A機關要資料，還要再特別開發一個方式，其實這一些當有API提供的時候，這些都可以降低一些重複開發的成本。

另外一個效益是，未來可以更容易去導入一些有關於Schema的資料標準，像API提供的資料，API是一個比較有彈性的開發方式，所以有時候的回傳值，別人在使用的時候，完全不知道哪一個欄位什麼東西，只要看到這一份API說明文件的人，就可以很容易理解每一個API欄位的值為何，這是它的效益。

我們目前有沒有採用這一個成果？有的，一個是交通部的PTX平台，他們非常厲害，他們規劃很久，整合了臺灣公共運輸的資訊。除了把他們的API通通提供一個符合OAS的文件之外，他們直接把它變成是線上的API說明，也就是在架設網站的時候，你完全不需要額外的功，就可以直接把這一些OAS文件變成網站API使用說明的一部分。

我們來看一下demo，這個是PTX的使用說明（如網站），這裡可以直接點下去，就會展開出類似剛剛的型態，這裡面會有針對API基本功能的描述、參數的描述，一樣有各個定義，甚至可以直接進行測試。你在完成之後，不用再作額外的轉譯動作。

接著是我們討論的時間，請政委主持。

隨時大家想講什麼，舉手跟不舉手都可以講，線上跟線下都可以，我們就一個個來討論，議程完全由大家決定，討論到上面沒有問題，大家才離開。

sli.do：「原來用web service 開發的文件是否要轉換？」

第一個是大家最關心的是，因為這一整套東西，如果像我一樣，在這一行做了滿久的話，其實很久以前WSDL那一整套SOA都已經講過的，現在講的觀念，基本上是XML base的那一個世界其實都已經說過了。

OAS跟SOA到底有什麼主要的差別，我想分享一下。現在在做OAS，其實完全增加我們本來就有在做這一種文件API說明文件的機器可讀性，我們只管說明文件，什麼都不管。以前SOA不是這樣，以前SOA要discovery的時候，要跟上下左右各部門的人都已經喬好說什麼參數、Schema，裡面要符合什麼性別，什麼都要事先約好，這並不是很適合我們的資訊環境，因為很多單位都需要開發自己的程式，而程式開發的過程中，也不是為了跟別人交換，是為了解決自己的問題，因此對欄位需要保留相當多的彈性。

因此在很多情況下，即使是用API作開發，這個API並不是共通性的，意思是並沒有想要給別的機關copy，也沒有想要copy別的機關，如果由上而下一律說這個領域的所有API都必須用完全相同的Schema，其實實務上會對大家造成負擔。

我們其實現在是用點對點的推法，我們講的是當每一個機關的資訊系統，當大家準備好要給其他人介接的時候，給大家看得懂的按圖施工的圖，有點像是我們給一般去遊樂設施時，會畫一張場地的簡圖給大家看，你在這邊、出口在這邊之類的，絕對不是把當年設計師施工的那個圖，包含地下管線都放在指示牌上，也沒有必要。

所以以前SOA的時候，大家先約好裡面的管線、地下的管線要怎麼排，那個都要先約好才能推行，實務上做得到，但是要由上而下的規劃。

現在的做法是自己裡面怎麼做都沒有關係，但是外面希望一個入口跟出口，跟別人交換的時候，指示牌要用這個方式做出來，這個是基本概念上的不同。

所以具體的回應是，如果本來的是如果本來的Web service沒有打算要換成RESTful API，其實現在有很多自動API的工具，本來是Web service、SOAP的，前面可以放一個proxy，馬上就幫你轉成REST，這個事實上是很容易的。

但是如果你沒有動機要做這一件事的話，這個規範並不強迫你做這一件事；但是如果有動機做這一件事的話，我們現在有一個很簡單的方法，可以把本來SOAP的WSDL的描述，變成新的OAS描述，這是全自動的。

如果你有publish之後，有一種類似像contract的感覺，別人就會針對這個寫程式了，這個時候如果你未來再去改它，你將來會比較容易，如果要刪的話就加版本號了，這個時候就開始有維護的責任出現。所以現在並沒有準備好要做這個轉換的話，這個沒有強制性，並沒有要大家去轉換，這是大家具體的回答。

有一大堆打招呼的，我們就一一打招呼（笑）。

sli.do：「從機器可讀的oas，可以自動產生程式碼嗎？」

是可以的。而且它產生的程式碼其實是跨語言的，並沒有特別挑語言，當初為何會挑OAS？就是因為之前兩個主要描述API的文件，一個叫做Swagger、一個叫做API Blueprint，這兩家願意合併成OAS，也就是說基本上toolkit的支援、所有的大廠，會發現絕大部分的大廠都在上面，所以本來他們自己就在他們的開發文件裡面，會提供從OAS轉到不管是測試用的……按圖施工會有一個機器人幫你確保說你說入口的地方都進得去，出口的地方都出得來，這種測試的東西。

又或者是給一般普通開發者的SDK，但產生出來的這個程式碼多好用，取決於你在那一個OAS的文件裡面寫到多細，如果把JSON Schema都寫進去，也就是每一個API的傳回值或者是post給它的值，每個欄位、型別都已經寫好了，這樣當然就可以產生出一大堆正確的物件、類型，所有這一些東西都會出來，如果你只寫一行說這個是入口、那個是出口，但是不給JSON Schema，當然只能產生出方法，並不是魔法。你寫進去多少完全是看你，但是你寫進去越多，就越省未來開發者的時間，大概是這樣。

sli.do：「可以於會後提供簡報資料嗎？」

應該是可以的，就直接丟到sli.do就好了，等你有空就貼到sli.do去。

sli.do：「製作OAS說明有無第三方工具可以使用？」

有，有相當多。如果你找Swagger的話，你可以找到有很多toolkit，從你完全不會需要程式，只需要打字的Swagger UI，到你失去攔截那一個實際做http的資料，然後從範例裡面自動產生的，那個也有。

如果是本來在程式裡面就已經有一堆Schema，你的程式本來就是前後端分離建置，像你用React或者用Angular，用這種新的，在前端使用瀏覽器的端化介面，伺服器端只提供API的話，甚至也可以用你前端的這一些程式裡面去產生出OAS來，這些工具都有的。

這也是新的趨勢，隨著手機在內的各種運算平台的運算能力增加，現在大家開始慢慢可以接受UI在瀏覽去端化的概念，如果有用過Google App的話，就可以知道在瀏覽去端化介面，其實感覺滿快、順的，不需要在伺服器端化介面。

瀏覽器端化介面，伺服器端要出什麼？就是要出API，任何人都可以來幫你畫介面，這一件事就是靠OAS達成的。就好比像我們現在只有一個桌面版，可是有人真的很想要有手機版或者是對話機器人版或者是VR版之類的，以前都要分別各種開發。

現在可以說OAS在這邊，就再包一個比較小的廠商，跟本來的廠商甚至不認識、競爭關係及敵對關係，都無所謂，做的事情就是把本來做的東西在某個別的載體上使用，所以這樣的好處是可以前後端分開切，然後分開包出去，如果失敗了也不會影響到資料庫。

因此我覺得第三方工具完全是看開發流程怎麼先行，UML先行就先送那邊做；或者如果是敏捷的話，會先有一堆測試，先從測試開始做，各端都會有產生OAS的方式。因為每個開發型態不同，我沒有辦法一一表列，但是我們未來會提供連結，事實上Open API組織的Github上就有許多的連結。

接著有人問一個很或的問題，也就是規範草案的格式強制性有多大？像有一個版本號，有一個V1、V2、V3，如果現在沒有版本，是不是因為這一個規範出來了，所以變成非這一個版本不可？

我們這邊的規範其實是新簽合約或者是更新舊系統的時候，可以變成你去要求廠商的項目，我們的效力只到這邊而已，並沒有回溯適用的問題，也就是有信賴保護——最近這幾天真的滿重要的（笑）——沒有回溯適用的問題。

另外一件事是，這個東西是你可以因地制宜的，如果你覺得有相當好的理由，這個廠商實在不適合用RESTful API，適合用別的東西，這個並沒有強迫你用特定任何的風格，如果你是RESTful API，你要做一個API文件，這樣做比較好，因為大家按圖施工，大家看得是同一個圖。

如果你覺得你需要一個binary API，根本就不要叫API，你從頭傳就好了，那是你的工程學領，當你用那樣工法的時候，那個東西完全規範不到你，這並不是限制到大家的權責，而是你認為RESTful API是好用的……為何會用RESTful API的原因？是因為希望第三方的開發者來，第三方可以是民間或其他機關，或者是機關內部的交換，都有可能，但最適合的是，兩邊的廠商彼此間彼此不認識的情況。這個時候如果你用RESTful API的話，這個是節省大家時間的工具，如果實際的社會情況不是這樣子，也不用RESTful API。

Sli.do：「OAS如果需要多語系，怎麼做？（通常國內Api都是中文為主，但是有時候英文會方便閱讀」

這個是非常好的問題，理論上剛剛在簡報裡面有一個叫做APIs.json，一個叫做API條列式，基本上這個東西可以把網站上英文的API說明、中文的API說明，你就可以在網頁的relation那邊可以寫APIs.json，一個是英文版、一個是中文版。

至YAML要如何做中、英文翻譯，這個其實是你可以有一個半自動翻譯的方法，你有一個glossary，就是某些特定的字要翻成什麼，或者用機器翻譯，有一個前置作業，好比以中文為主，這個前置作業把裡面所有的文字欄位的字都先用機器翻譯成英文，只要稍微再去編輯一下就好了，目前機器翻譯的準確率還算滿高的，比你自己從頭翻絕對是比較省力，所以這個是具體的，也就是可以用JSON或者YAML裡面的文字欄位的部分，然後餵到一個自動翻譯的pipeline裡面，然後再修改它。

但是即使完全都沒有，就是按JSON檔，打開JSON或YAML檔，其實把這一個JSON或者是YAML直接丟到Google或者是微軟翻譯，翻出來的東西還是可以看，所以其實還ok，這整件事我覺得就是以不額外增加大家的麻煩為原則，當有一個英文OAS需求的時候，你就再多加一個entry，如果沒有這個需求就不加。

有editor跟轉換器，這個都沒有問題。

Sli.do：「2017 OWASP將API列入TOP 10，草案未來是否有相關規範？」

我們手上的這一個公共應用程式介面規範，不知道有沒有特別把OAS考慮進去，即使有規範的話，會在別的地方規範。

有一位Hello的，那就繼續Hello；有一位趁亂告白的（笑）。

有一位問的是為什麼要寫結構化資料的YAML檔或者是JSON檔，為什麼不寫一些範例檔？

這個是非常好的提問，我要特別說的是，其實在說明欄位裡面，可以用一個格式叫做markdown，各位如果有聽說過的話，就是一個讓你比較容易寫html的方法，好比像html要寫H1，還要關掉H1，很不方便，但是markdown，可以「＃ 」，就是大標題的意思，然後二標題的意思是「＃＃ 」。所以可以用這一種滿容易撰寫的方法來寫使用的範例，或者來寫額外想要參考的東西，而且裡面其實都有內嵌html，所以如果有html寫到一半的說明、流程圖，或者是連到別的參考資料，像會連到本來的那一份PDF裡面，都可以在說明欄位的markdown裡面用html語法或者用markdown語法，這兩個是交叉的，把這些額外的資訊揭露出來，這樣的話，透過自動化的工具，實際轉成PDF或轉成線上文件的時候，這一些東西就會保留。

所以，其實取代的並不是整本東西都不能用自然語言描述，只是自然語言描述裡面一直重複的部分，用一些機器的欄位讓機器比較容易瞭解。

裡面還有很多可以寫給人看的段落，好比說明書裡面已經有了，那就是要保留，就是在OAS editor裡面，可以一直貼上本來說明書裡面的使用範例也好，或者是任何給人看的東西也好。

雖然機器看不懂，但在機器自動產生出說明書的時候，至少那個說明書的資訊不會比本來的說明書資訊少。對開發者來講，也知道發生問題的時候，可以參照怎麼樣的問題排除方法，或者是裡面其實已經把如何用API說明得很清楚了，看了之後就懂；當然就是隨著機器學習的進步，說不定未來機器也會懂，但這不是一、兩年內可以懂的。

Sli.do：「Page25的APIs.json是OAS文件內的嗎？」

不是。是更抽一層上來的，那個概念是sidemap，就是我們進了一個網站之後，然後會有一個網址的地圖，把所有人可以看的主路徑都列出來，這樣就不用一直到裡面找。所以APIs.json其實就有一點像給機器看的網站地圖，把這一個網站有用到的API都列出來，不一定是這一個網站本身開發的，可能用了別家的，或者是這一個網站有多於一個廠商共同作成，每一個貢獻不同的OAS說明。

OAS版本也許有一些還在用API Blueprint或者是Swagger，甚至網站的部分有一些是更別的WSDL隨便什麼東西來描述。APIs.json不挑，不是一定只有OAS的才放進去，因為APIs.json只要是API就可以放進去，就是給一個機器讀說這一個網站用到哪一些不同的API技術。

所以大概的感覺就是說，APIs.json為什麼要放，就是希望未來如果有多於一個不同API來源或是你的API多一個語言版本，又或者是任何情況，都可以在APIs.json裡面去描述它，但它並不是必要的，而是有這一個需要才這樣放進去，不然這一個網站有一個Open APIs.json檔就可以了，並不是要用外面的這一個跨API或多APIs.json的標準，不是OAS的一部分。

我不知道這一個提問者對於第25頁，也就是對文字上有疑慮嗎？剛剛政委解釋的是技術方面的問題，如果是的話，可能我們這邊表達的並不是非常清楚，其實我們想要表達的意思是這一個文件裡面有一個是header跟API link。

就是APIs.json是總目錄，文字具體可以調整成「建議可於首頁html文件或者是首頁的Web服務的header」，因為基本上就是一個link relation，所以當然就是在html裡面放，或者是可以在http的header裡面放，有一點像這一個網站給人看，以前可能會放RSS，那是給機器看，這個也是很類似RSS概念，只是給API使用者看的概念，這並沒有強制性，再次講一次。base practice。

Sli.do：「為加強公私協作及對民間宣導政府資訊系統的標準，是否在規範正式定頒後，請國發會另開說明會，對象可能是二級機關所屬機關單位的承辦人甚至是廠商？」

我們有逐字稿的目的是各位可以把逐字稿帶回去，就可以把大家問的問題、討論的過程或者是答案，實際去跟大家說。說完之後一定會有更多的問題，所以我們收攏了更多的問題，第一個是隨時歡迎寫信給我或者是到「ask.pdis.tw」問我，基本上我二十四小時之內應該都會回答的。

這是我們PDIS網頁（投影網站） ，在「How we work」是放會議結束後兩個禮拜的逐字稿，我入閣後主持的所有事情都在這裡，今天的討論之後也會放在這上面，這是具體可以分享給所有朋友的，這個是一件事。

如果有額外想要問的話，可以再來聯繫我們。

如果各位覺得不是錄影、錄音、逐字稿或文件上的說明，需要更多的互動，也讓國發會知道，其實從我進來開始，我們就是用API first的方式開發相當多的系統，有些在PDIS網頁上有完整的說明，也就是公共民生物聯網裡面的災防系統，或者是菜價看板的系統，或者是PDIS網站本身，或者是「data.gov」的東西，其實我們都有一些經驗，也有一些同仁已經可以當講師跟大家分享，也不一定只有我一個，如果大家想要book時間的話，都很歡迎跟我們聯絡。

Sli.do：「如資料非公開（含個資），如雙方已建置安全網路且均同意，是否可用其他方式傳輸（如資料庫view）？」

當然。因為這個就沒有共通性可言，本來就沒有讓不認識的廠商接取，這個就不在今天的討論範圍之內。在這種情況下，不管用Rthink、 FTP、UUCP，都沒有關係。我們用RESTful API的目的是要讓不認識、陌生的第三方開發者可以接取，不一定是開放資料，也不一定是外面的人可以接取，這裡的陌生廠商也包含同一個廠商的別的需用機關，可以是intranet或者是internet，整個目的是要讓不特定的廠商來接取。

但是如果一開始就是兩個特定的，就是約好用別的東西交換，就不在這一個不特定的共通性裡面，根本不需要共通性，在這樣的情況下，這個規範跟大家沒有關係。

當然我們在規劃的時候，也許現在看起來只有兩個互相think，也許在未來的時候，也許有可能讓別的機關或是跨機關使用。我的經驗是，只要有第一個跨機關的使用者來的時候，你有兩個選擇，也就是專門做一版給你，也就是要維護那一版的format很久，或者可以說你把你的需求想辦法用OAS表達出來，把它講清楚，我們請就廠商按圖施工，這個並不是只做給他，而是未來相同需求都可以繼續這樣使用，也不一定轉成Open data——這個是完全另外一回事——但第二次、第三次被索資的時候，不用一直出第二版、第三版去長成不一樣的東西，去符合各個不同上下左右機關的需求，可以在第一次來的時候，就說我們用OAS談好，這是另外一個可能的用法。

如果這一套系統真的就是這兩個一直互相交換，一直都沒有第三個人來問，根本不需要用這一套。

Sli.do：「OpenAPI Object之固定欄位METADATA是原來『政府資料開放跨平台介接規範』沒有的，是否只有API，都得加入？」

不是。剛剛已經講得比較清楚，這邊的描述比起上一版之所以擴充，因為上版基上是read only的API，也有批次寫入的部分，但並不是Rest裡面的每一個動詞——get、put、post——或者包含未來patch、delet之類都在裡面。這一次用OAS是把RESTful都包含在裡面，所以理論上用http來傳輸的，以JSON為主的API，都可以用METADATA來描述。但並不是你的API本來不符合這一個形狀，或者根本不是RESTful，本來就是SOAP，或者是其他根本也不是http API，根本就是SCP，這一些都得加入，沒有這一種事。

Sli.do：「可以大概說明一下何謂YML？」

YAML是我的好朋友Brian Ingerson發明的——沒有啦，他是三個發明人之一——"YAML Ain’t a Markup Language"，展開的意思是YAML不是一個標記語言，基本上就是讓你少打很多字的JSON，如果大概知道JSON是做什麼的話，大概可以理解YAML是在做什麼。

也就是參考了Pison或者是其他Ruby這類的語言，可以發現靠縮排就可以做到一些本來打大括弧跟逗號才可以做到的事，可以把它想成JSON的另外一種語法，這是一件事，另外一件事是加入了是refference的概念。

也就是會自動幫你展開成reference的概念，所以當build to（音譯）跟ship to（音譯）是相同的時候，就不用再打一遍，會自動展開成那個reference，所以當你JSON結構裡面有非常多重複段落的時候，也就是類似像XML reference的概念，所以可以少打很多字，整個目的是讓JSON少打很多字，還表達得出來。

當OAS被用JSON跟YAML表示的時候，這個是完全等價的，這兩個是可以隨時互相轉換，如果完全沒有任何的工具，只在瀏覽器裡面開起來，開JSON的話，大家就不想看了，但是看YAML的話，大家看得下去，只是這個差別而已。

Sli.do：「APIs.json是否可以自動產生？」

這個是非常好的問題。這看伺服器的架構，如果伺服器的架構比現在的RESTful API更結構化，好比你用All data開發或GraphQL開發，你用這種伺服器本身是API伺服器的感覺來開發，當然你跟它要它的API的說明列表，就會自動生一個說明列表給你，這個時候的自動產生機是非常容易的。

但是如果現在server後端，仍然是比較老式的三層架構或資料庫，透過一個後端程式去畫html出來，即使有API，也是額外畫出來的，這時就要去問後面的ASP net或者是Java的web logic說裡面到底哪一些是畫給機器看的、哪一些是給人看的，還是要做一些盤點的工作，哪一些出的東西是給JSON，而且是給機器看的，哪一些是html，而不是別的格式，其實不是給機器看的，可是這個時候也不是只看格式而已，因為有些雖然出JSON，但也不是給別人用的，是給內部管線的一部分，並沒有準備好給外部使用，所以還是要作清點。

如果開始的點，不是伺服器本身是前後分離伺服器的話，就是給開發者看的說明書或「.sdk」，這兩個點開始是最容易的，如果要從中間開始的話，就要有一些盤點的工作。

Sli.do：「目前提供的API服務，會遇到無法追蹤使用者的問題（除ip可解釋時是可追是例外），這部分想過使用登記但又怕造成使用者困擾，我們應怎樣才有彈性」

為什麼是講「追蹤使用者」？當然如果你有一個很好的理由想要追蹤使用者的話，OAS裡面其實有相當好的規範，就是可以要求它要有一個token，不管是用OAuth Bearer Token，或者是用htpl的，你可以選這一個，雖然現在比較少人用這一個了，或者是其他第三方登入或者是認證方式，可以寫在OAS。

這個是我們講OAS，而不講Open API，因為會有點跟Open Data混淆，因為Open的意思是任何人都可以來下載、存取等等，但是我們如果用OAS的話，其實推翻的是共通性，並不一定完全開放。如果要申請帳號密碼才可以進來，或者需要某種整合登入，像E政府的東西才可以進來，也還是可以繼續用OAS去做描述，可以把登入的flow，也就是如何取得認證才回得來，這個東西也在OAS裡面描述，所以這樣的話，大家一看到這一個文件就知道要登入才能進來，進來之後才有Token，這個才會是變成未來要追蹤我的方法，這個等於是跟使用者講清楚，就比較不會有額外的疑慮；或者有更多的疑慮，就看你講得多清楚而已，但是至少不用IP取材。

簡單來講，這個是可以你要求它透過某個身分認證的方式，才進得來，等於讓你追蹤，但這樣子當然會讓它願意使用的人下降，但你有相當好的理由這樣做的話，你是可以做這一個限制，如果不來登記的話，一個月只讓你存取一千字之類的，你有很多的想法。

又或者不來登記，只能用Get的API，但是post非登記不可，這個就比較講得通了，畢竟是寫入資料，要知道是誰寫入資料等等，這都可以在OAS裡面加以規範。

Sli.do：「為了降低廠商開發及驗收難度，能否簡化openapi的spec？還是規範的隱藏目的之一是要讓國內這些廢柴廠商提升水準？」

這個好困難的問題（笑）。這個spec如果實際進去看，絕大部分都可以，shoot一點點，must的真的不多，這個是非常循循善誘的spec，制訂這一些spec的朋友們——包含我在裡面——都是推WSDL、SOA，然後效果不是很好。

所以我們現在的想法是，我們不應該勉強開發者或系統維運者做任何他們不想做的事，所以我們提供的，除了真的有一些欄位名稱，真的大家要同一，JSON Schema大家至少要同一版的這種東西，當然非其一不可；除此之外，我們都沒有那麼強制性，即使不附JSON Schema，即使所有的description欄位都是空的，這樣出的一本說明書，每一頁翻過來等於只有大綱，大綱翻過來就是空的，這樣也許會造成反彈，那就是政治性的問題，並不是技術性的問題。

我要講的就是說，它還滿鬆的，從廠商的角度來看，其實並不一定那麼要填到鉅細靡遺，是各位在開案子的時候，可以再做額外的要求，所以要讓國內的廢柴廠商提升水準的話，你的要求是可以建立在OAS的要求再往上，好比像我剛剛所講每一個API存取的說明欄位，至少要附兩個不同語言的範例程式，各一百四十個字以上的說明，你可以在OAS上，要求到非常細，但OAS本身並沒有要求到這麼細。

如果提出這麼多額外不合理要求的時候，你可以改幾行，就可以在驗收的時候，沒有達成的，機器就自動不過，這是對各位的幫助。

但是我們的base line並沒有這一個想法，並不一定要讓國內的廢柴廠商提升水準，我們最原初的想法只是大家用各種不同的方式，大家用word檔、PDF及各種不同的方式來描述API，我們在審視的時候，其實是非常難對接的，像公民生互聯網一案，就是五個系統以上的大系統裡面又非常多子系統的對接，這個接對接沒有機器可讀的方法，沒有人看M x N的對接方法，那其實是非常累。如果讓最懂資訊的幕僚朋友們都花在這一件事上，就不用做政策或別的系統，整個目的是把任何人來做，結果都一樣的東西，讓它自動化。

Sli.do：「草案p.4欄位名稱security代表的定義是？」

要存取API，要先滿足哪一個授權需求，就是剛剛所講的登入要求或者是需要一些特定的Bearer Token或者是OAuth Flow這一些東西，因為這個是簡版，所以詳版可以參考Github上面OAS的specification，你到Open API.next的分頁，就可以看到詳細的security。

Sli.do：「請問對內對外的api均須follow嗎？」

因為我這個不溯及既往，當你對你的API，仍然是有共通性，你覺得未來隨時有可能接上來，而不是你認識的人接上來的時候，這個時候才需要follow，如果你現在是固定的兩個系統彼此間，每一個晚上FTP試，但別人都不會進FTP站，這當然跟我們沒有關係，這個不需要follow的，重點是共通性，因此共通性與否其實是各位自己判斷的，並不是我們中央突然間說所有API變成public API，沒有一個國家這樣搞，我們也不是這樣搞。

對外的API是另外一回事，我們希望對外的部分本來是提供RESTful API，而且本來也有一份說明文件，是不是可以在下一次系統維護的約，或者是換一個廠商的時候，去解決每一次換的廠商之後，所有service的全部爛掉的問題，如果你也覺得是一個問題的話，這個是很好用的工具。

但是再次講的是，這是廠商能力的加分項目，如果做不到的話，絕對不能用這一個廠商，不是這個意思。

我們在做的是給大家一些政策上的工具，如果想要要求到更嚴格或者想要更多的話，有一些準據可以寫；但是如果都不做這一件事，其實跟現在的狀況是沒有兩樣的，只有願意用RESTful、OAS的方式來開發的案子，才會用這一個案子來開發，所有其他的，像主觀判定不適用，還是不適用，這個是沒有關係的。

Sli.do：「在機關內常被問有誰用有什麼民間app在使用，openapi是否也會要求績效？」

我們是推API，不是推KPI，這個是不一樣的事（笑），不能搞混，如果搞混，會有相當多不良的後果。我對API有相當有興趣，因為可以節省很多重複的開發工作，KPI好像效果相反，反而讓大家做很多重複的工作，所以我對KPI沒有興趣。

雖然在某些特定的計畫案裡面，好比像公共民生物聯網，會說希望把這五個大系統裡面，把四十個都轉成OAS的格式，有一些示範的作用，有一些真的是跨局處、司處、部會的系統，每一個開發商都不認識每一個開發商，所以如果不用共通性的方式來做的話，其實也不知道該怎麼做，所以這個特別是適合哪一個特性，才會有人寫在這個KPI裡面。

如果不適合特別適合那個特性，而硬要大家做的話，那就會變成你的API文件都寫出來，但沒有人來接，到底寫給誰來看？你也可以想成是更好的說明文件格式，但如果一直都只是給下一個廠商看的話，除非在開的時候，就知道要這一些服務、就是要要求這一些廠商做，如果你不看、廠商也不看，這個沒有意義，就是冗工。

如果最好是下一個廠商或者是第三方開發者也看或者是別的部會也看，這個成立的時候，你訂這個KPI也許有意義，這個是各位的自由，但我們不會從中央的角度來看說每一個部會要接下來多少個，這個跟以前推Open Data完全不一樣的，請各位不用擔心，我們不會說每個部會要交多少資料集進來的方法推，之前那樣推，我其實不是很贊成，不過那個是以前的事（笑）。

Sli.do：「可否在『政府開放平台』上開關讓機關可發布的OAS專區？」

事實上data.gov裡面本來就有以API作為服務形式的這種METADATA，本來在publish一個資料集上去的時候，你就可以勾說這不是批次下載，而是API的端點，本來就可以用，用這個的好像還不是很多——各位數的——本來的能力就在那邊了，如果想要用的話，就歡迎使用。

Sli.do：「跨機關API，非開放API也得follow？」

我把它唸成（得到）的「得」，你如果認為這一個跨機關，未來可能卡更奧多的機關，或者是雙方的廠商換的話，這個是得follow，這個是未來按圖施工的人一個好方法，但如果你一段，可能開發的費用會增加太多，或者是不會有跨機關加入的話，你也不一定要follow，這完全是機關自己判斷的。

Sli.do：「目前已提供出去的OPENAPI，已經有很多民間單位在使用，如果使用新的規範，此址語法不同，涉及很多單位需要改接，且OPENAPI都是開放，沒有聯繫窗口？是否有配套措施跟因應？」

這個是好幾個問題，我一個個回答：

第一，不是表示publish OAS之後，本來提供的東西都要棄用，我們沒有這樣的規範，我們即使是要求廠商有這樣的能力、提供這樣的東西，不表示本來所在提供的服務位置要棄用。

我們如果把強制棄用寫進去的話，後果是很嚴重的，意思是提供前後分離版本之後，甚至網站本身都要啟用，如果沒有Java script的瀏覽器就不能看我們的網站，但不是這樣子，是要優雅回溯到比較舊的版本的瀏覽器，或者是本來已經在使用的使用者。

即使現在提供的這一個東西，本來的那一個東西打算維護到什麼時候，就維護到什麼時候，並沒有要求什麼時候一定要日落、下山，但新的開發者如果用這套東西，自己產生測試跟程式碼的話，你未來要跟他討價還價的時候，也就是現在要加一個欄位、減一個欄位，你們比較容易就事共事，你們在討論同一個empoint。

如果兩、三個系統用了OAS之後，發現他們用的JSON Schema是一致的，這樣對於第三方的開發者來講就不用重複開發出一模一樣的東西，這個是具體的好處，但舊的方式並不是這樣子就非得棄用不可，這個具體說明一下。

接著，當你開發給不特定第三人的時候有沒有聯繫的窗口？這個是markdown語法耗用的地方，就可以在OAS的說明文件最上面說如果有問題的話，請打「02」或者是「0800」什麼的，就可以聯絡到我們的聯繫窗口，這也可以寫在OAS規範裡面的。

在data.gov平台裡面有一個聯繫窗口的METADATA，所以如果你是提供任何人都可以來接用，不是機關內部接用服務的話，把那個東西到publish.gov的時候，也可以留下一些窗口跟聯絡的管道，這個是配套。但如果是內部使用的話，也可以在OAS的說明欄位說如果碰到問題要問誰等等，這個都可以直接寫在裡面的。

Sli.do：「GeoJson也可以用嗎？」

是的，也可以使用。其實它描述的是一些端點，這一些東西端點會回傳的東西，如果是JSON的話，可以描述得更細。但即使回傳的不是JSON，你也可以說這個端點會回傳XML，然後意義是這樣，雖然它的描述可能要用什麼別的語言來描述，即使回傳是純文字好了，你也可以說這個task plan（音譯），這樣寫了還是比沒有寫的好，當然裡面的結構化就不可能要求這麼多，因此你現在有很好的結構化、JSON Schema，你當然就可以直接套上去，這個是可以直接用的，即使不描述也不會怎麼樣。

Sli.do：「服務路徑URL結構定義，是否得按照草案上的規範範例格式製作？如果原來的路徑URL結構與草案不同，是否需要重改？」

這個是建議；現在的開發其實都已經可以做到同一個可以在很多不同的網址，所以新網址的時候，舊的好比是301可以重新導向到新網址，這個是最簡單的方法，或者是兩個都併行，互相不重新導向，這也是都可以接受的。

Sli.do：「影像、聲音、圖資等是適用？」

應該是說都適用。只要有一個辦法去描述哪一種東西，至少可以描述到你會傳回什麼，是什麼形式、意義是什麼，當你給不同參數的時候，哪一些參數有意義，好比像圖片，也許你會有一個size等於什麼，那個也許pixel，如果不特別在OAS裡面寫pixel的話，他怎麼知道要傳500？怎麼不知道是small media large？或者是說你們的API的size只能small media large，就知道這三個值有意義，因此即使是傳回圖片，去描述它的參數還是有意義的；當然回傳的時候，就會給你一個Image JPAC，這樣其實就要知道準備好JPAC解碼器，而不是什麼PNG的解碼器，所以這還是有幫助，並不是只限於JSON。

Sli.do：「目前已有開放之API，是否每個都需要依照規範草案，增加OAS？」

同樣的，因為我們是放在資訊採購服務，所以你下一次採購或升級的時候，就說中央有這一個規範，然後中央要求做這一件事；但並不是馬上要更改合約跟做這一件事，即使經過判斷之後，覺得這根本不好用，不要用就是了，我並沒有一定要……我再次聲明，這個是API，並不是KPI，並沒有要一年內交出二十個東西，我絕對不會用這一種方式推的。

Sli.do：「請問是否該OAS規範的推動與適用的時程規劃，以便機關預做準備。」

之後國發會會有一個專頁或是專區，對不對？把相關的東西都公布在上面。這一個東西公布，我們還在等國外的標準組織，現在這一個標準制定是大家都認為沒有問題了，如果真的有人有很嚴重的問題，現在提出還是會受理的，如果大家都沒有很嚴重的問題，到月底都沒有提出——現在看起來是沒有——下個月大概20日左右，這個會final，然後就會publish，變成OAS3的定版。

所有一切的討論、適用時程，其實是要在那一個時間點之後，才真正可以這樣子來做，因為畢竟我們也不知道從現在到月中，其實我真的沒有看到任何人有任何意見，但誰知道明天會發生什麼事呢？還是要在下個月月中真的publish，我們才能在那一個專區給大家一個網址，然後往下推行。

因此從現在開始算的一個月左右，比較是先期準備的一個時間，也就是大家如果有不太瞭解的部分、詢問的部分，這一件事我們再多收攏幾次，等到spec完全final，我們再推行。

Sli.do：「現有的restful不符合OAS spec，也能用工具做出說明文件嗎？」

是的，當然可以。OAS是無關科技的一份文件，即使完全不restful，我們打一個最極端的比方，你只有一個post API，empoint叫做Slash SOAP，根本不是restful的文件，就是一個SOAP，你還是可以在OAS裡面寫一行說這個是SOAP service，你要post到上面，必須是XML，也會回應XML，但是說明請看到WDL檔，即使在最極端的情況下，OAS還是可以跟大家說這是最壞的情況，還是可以做這一件事。

Sli.do：「Opendata/api/圖資的meta是否可整合？」

非常好的問題。我們在開放資料上，如果是JSON資料或者是CSV資料，或者是JSON或者是XML資料，其實這些資料都有描述欄位的方法，其實CSV可以沿用JSON Schema，或者可以用Data Package，JSON當然有JSON Schema，GeoJSON或者是不同的透過JSON，還有它自己的Schema，XML當然有SSV這一類的Schema。

但是所有這一些METADATA沒有很好的方法打包在一起，所以即使你的Open Data，好比現在有四個可以給別人下載的地方，但這其實並不是真正寫入式的API，只能讀取，但用OAS去描述這四個Open Data端點的時候，還是可以把JSON Schema附上去，也就是可以用來作為描述Open Data端點的方法，也就是用OAS，但裡面都是gap，並不會有post或boot或delet，但裡面都是一個資料集，也就是在參數那邊好比limit等於多少、也就是一頁傳回多少，還是可以有一些跟批次下載不一樣的調控方法。

但是即使是批次下載，也可以用OAS描述批次下載會下載到什麼的Schema，這個同樣對於CSV或者是資料集都適用的。

Sli.do：「可以用openapi來串聯Api間的資料流跟cors相關設定嗎？」

你希望哪一些服務來使用，好比這一個機關跟其他三個串接，在跨網域的自動存取裡面，就可以開給不同網域的這一些客戶端使用，當然這一個東西不一定要用cors來做，你可以用各種各樣的方式來做（例如proxy），但這是技術細節了。

好處是因為有一份OAS文件，所以在設定cors的路徑，或者是在設定代理伺服器、API中介者的時候，這一些大部分的現在軟體都可以直接丟OAS進去，然後就把這一個規則跟資料集變成設定的選項，所以可以省一個步驟。

而這一件事在未來，隨著大廠OAS3支援越來越多的時候，這一個狀況就會越有感，目前OAS2的時候，我們已經有看到相當多的第三方工具在提供這樣的事情。

未來會變成API management的地方，也就是在儀表板上看到提供的服務有哪一些，這一個API之間組成的。

我們再往前講的話是，開始把裡面的某一個部分變成Microservice，然後每一個部分都可以丟到像HGR這樣子的雲端自動負載的事情，這個是很後面的事情；現在要做的事是我們提供服務的出口、入口讓大家看到，只是到這裡而已。未來按圖施工，也就是大家看到之後，接下來這一個東西要如何重購，像報稅軟體是不是可以前後分離，也就是能不能用平板或Mac、Linux報稅，他們用的網站，有一點像報稅後端的客戶端，這個客戶端本身可以架在雲端，但這個後端仍然是在防守好好機房的前後分離感覺，我們慢慢會往這一個方向規劃、分享經驗，但OAS只是開始而已，並不會走到這裡，是會有一點幫助。

以上都講完了，可能有朋友沒有帶手機，沒有辦法連到Sli.do，有沒有現場想要討論或者是提出來的問題？

這個規範的目的，其實很難一眼看出目的是什麼，只是在做API的基礎建設，可能描述比較模糊，沒有辦法第一眼就瞭解目的為何。

我剛剛看了文件跟聽政委講之後，聽起來就像跟Open API本身並沒有直接關聯，而是如果系統有做API的話，需要做一個API的敘述文件，感覺像這樣子，範圍也不是全面性的推動，像是一個指南，也就是要給做的人。

而這個目的跟範圍，在這裡面規範的草案，其實是滿模糊的，所以很難第一眼就判斷出來。

如果前面可以釐清，後面附件2的內容就比較好連結，因為附件2目前都是英文，因此其實很難全部看過一次。但如果內容順過一次之後，其實就知道附件2大部分都在講哪一種樣態所需要提供的描述規範，大概是這樣子。

這個規範跟Open API沒有直接的關聯，還沒有到那個程度。

另外，剛剛有講到是目的、範圍及內容，目的跟範圍可能要明確一點。內容的話，希望可以再更完整一點，目前還沒有翻完。

若講到Open API的話，API的授權跟驗證的部分，希望在後面訂定Open API的規範時候，希望可以再注意到這一點。

這個規範有訂三塊，也就是data in跟data out，其實data out是各資料平台都已經在處理，data in是民間想要的部分，其實Open Data是為了要加值應用，Open API則可以吸引更多人來加值應用，大家會對Open Data是給出去，Open API比較像是收進來。

如果未來要做Open API的話，可以先從線上系統層級先著手，然後再慢慢把一些實體電話檢舉的部分納入，以上建議，謝謝。

單一陳情系統就是非常好的例子，感謝主動提出來。

因為單一陳情系統，如果有人沒有用過的話，其實就是1999。那個單一陳情系統的特色是，以前是每個不同的陳情系統，其實不是為了API而開發的，所以會變成民間的第三方如果要接取的話，像小幫手之類的，就要必須爬那一個網友、猜那一些欄位的意思，然後虛擬一個瀏覽器按送出，如果廠商改一下，民間的API就爛掉了，以上不是廠商，最近就發生了（笑）。

這樣就增加大家的溝通成本，所以沒有好處，因此用一個大家都看得懂的API方式，用OAS的文件來說只要這樣接，保證不要亂掉，這樣就可以了，跟外面有一個讓彼此安心的合約概念。

所以未來任何陳請系統的欄位就不出這個，因此不管是陳請相似或者是相關的東西，都可以參照同樣的Schema，或甚至就是用完全同一份spec，關於噪音的陳請都可以來用同樣進線的KPI，只要自己配合的局處變多了，自然在這邊聲音就變大了，但不需要額外再寫文件或其他的東西，只要多一個報案的陳請類別就可以了，這是非常好的範例，非常感謝。

另外，剛才對於一開始想要解決什麼問題的範圍，還有這一份草案到底做什麼內容，希望能夠更具體做，因為反正有逐字稿，可以複製貼上上去，因此有比較好的說明方式，這個是非常具體的建議。

另外，等到未來用這種OAS方法建置出來的共通性API，真的對不特定人開放了，當然就會開始有執行的效率、資安及這位朋友問的會不會變成ddos的懶人包（對應 Sli.do：「openapi會不會變成ddos的懶人包？」）。

不過我想跟大家報告——我並不是做過這一種事，但是我朋友在做這一種事（笑）——他們絕對不是挑API，而是挑那一個網頁剛好看起來計算量最大，或者裡面有一些雜湊的東西，發現餵一些值進去，就可以讓它CPU飆高，絕對是挑那一些來打，而不是挑API來打。

API有一個攻擊表面跟防守表面，所以在測的時候，開六個API出來，其實把這六個防守好就沒事了，因為這整個系統對外的表面就這六個。

如果是透過網頁的話，尤其是透過一些可能還會被塞一些SQL沒有網頁程式的話，裡面就有雜湊、對撞而造成CPU過高預料的弱點，這一種攻擊表面非常非常大的。

這也就是為什麼剛剛所講的前後分離在資安上的好處，如果從伺服器的角度，從這六個表面出去，所有的介面都是在使用者的瀏覽器裡面或者是手機上面自己畫，即使打到了那個畫畫面的邏輯，只不過是把自己的CPU燒掉而已，跟你沒有關係，對你來講只要守住那六個API的標準就可以了，不用守透過這一個API建置出來不同服務的頁面，這是我們在資安管理上的好處。

我們不會列入想要解決的問題，因為是次發性的，也不是用API就不會被ddos，只是每次被ddos，然後每一次修好之後，每次要修的次數是可數的，也就是修好就是這六個，修好之後就不用再做別的事情了，但是舊的開發方式，也就是舊的廠商留下來某一個特定的網址，網頁裡面有個資，但是事實上下一手廠商不知道這一件事就被Google發現了，這一件事就會發生，大概是這樣子。

現場有沒有什麼問題？

其實國發會之前有訂「共通性資料存取應用程式介面API規範」，其實是訂給人看的API，我們希望未來有一部分可以給機器看，這兩個規範未來是不是可以整併放在一起，未來其實機關在遵循的時候，都會覺得這個部分要給人看的，原來傳統文件的API、說明文件。

這部分新的規範文件，未來是不是可以放在這裡面整併？這個是第一個問題。

再者，在這個適用的範圍當中，剛剛政委講得很清楚，這是給各機關去選用，而條文其實寫得不是那麼清楚，而是寫得很嚴謹，為「均應提供」，因此我認為更有彈性的話，應該語法就要修正。

第一：其實這一份是把本來的那一份，把本來那一份「資料存取」抬頭四個字拿掉的新版，但是舊的是直接merge新的，所以在那一份簡報裡面有很多「（舊版）」，意思就是我們沿用上一版。

意思是從我們的角度來看，並不是現在有兩個併行的規範，一個給人看、一個給機器看，而是我們把本來只給人看的規範，加了一個只給機器看所選用的段落變成新的規範，但是從舊的規範角度來看，其實是新版的概念，未來絕對不會有兩個合併的情況，是合併進新的規範。這樣可以嗎？

可以。

原本規範寫得比較嚴謹，從我們的文件寫得比較多，但這一份規範裡面三、四頁交代這一件事，裡面的部分給各機關適用，會不會有看這一份文件不是那麼清楚。最後可能還是在看OAS的技術文件，而不是在看政府應用的文件？

確實。因為OAS技術文件的中文翻譯老實說有完成一個草稿版，但因為中文翻譯的品質有非常大的精進空間，所以目前還在工作當中，最後是會有一個完整的部分。

我們也是在等下一個月中的核定板出來，才會說中文翻譯是定版，之前都是草稿版，這個確實是這樣。

本來是機關間開放資料集的整批互相交換，因此會寫到一些資料集整批互相的一些規範。這一些其實在新的裡面，其實所謂整批資料集互相交換，其實是OAS其中範圍之一，但是要交換的不是限於開放資料集了，甚至是需要登入、寫入跟log in的這一些東西都含括在裡面，因此當然在說明上會稍微抽象一些。但是我們覺得可以舉例，也就是在專業或者是專區上詳加說明的方式來因應。

接著應用範圍是寫「本規範適用於可將資料讀取或寫入應用程式介面」，為了使API具有共通性之特性，我想這裡的特性是「共通性之特性」的六字詮釋。從嚴解釋可以說沒有共通性或根本不需要共通性的API，我們都要讓它賦予共通性，也就是讓spec做到這一件事。

但這並不是我們的原意，我們的原意是如果API從你的角度來看，需要共通性，那本來就有共通性，這份文件是要適用、是有幫助的，但只要主觀判斷說其實沒有共通性或不需要共通性，這整份規範就不適用這一個服務，當時的利益是如此。

如果我們可以在說明當中說得更清楚、調整字樣的話，這沒有問題。原意是說共通性的內容是有好處，本來就有共通性，或者是下一版往共通性發展，來沿用這一份。

但是如果沒有共通性，像剛剛舉了一個很經典的例子，這兩個應用系統中間開Data base的view，這兩個系統中間完全是由SQL資料庫來控制，既沒有讓別人來接取，也絕對不會變成開放API，所以往機關內、機關外都沒有新的使用者，這個時候我們不會說共通性，絕對沒有共通性，這個時候絕對不會使用這個規範，這是很清楚的。

因此，我同意如果這樣寫的話，容易有兩、三種不同的讀法，因此至少在說明欄要寫清楚，這個我完全同意。

另外兩個問題，其實在規範成本第6頁，這裡有建議不同的版本。但是在第7頁的舉例範圍當中又有第一點，一個是目錄的版本，一個是OPI的範例當中所寫的版本。

到底目錄的版本跟API說明文件的版本，要不要一致？如果要一致的話，就都用V1，在目錄信上，可能覺得用這樣來表示的話，可能比較方便。

而這個版本要考量的是，文件跟目錄的一致性是不是要考量？或者是保留目前的做法？這個是第一個問題。

第二，基本上我們不希望有版本，因為其實有版本的話，OpenAPI的說明文件一直在更迭，因此最新的資料是不瞭解最新應用的版本是哪一版，今天可能是放在……像目前Open Data平台裡面有很多範例文件，但之前都沒有V1的版本。要打V1的版本，才可以把範例文件找出來。因此變更了說明文件，最好是從頭到尾都可能共同在讀那一份文件，我們就知道讀哪一些參數，然後去做相關讀取的應用，這個是建議。

第三，國安目前提供範例，我比較不建議提供這一個範例，因為這一個範例本身有做，不管有沒有傳入值，或者是那個值打錯，其實會把整批的資料集丟給你，所以或許舉交通部的案例集可能還比較有用，因為看起來這個案例集的組合，也就是沒有讓政府機關覺得做這一件事是有意義的，看到那個資料集所有的序號來講，可能正確性也不是那麼高，這個要著重一下。

我快速綜整，範例這一個東西是非常好的具體建議，我們就這樣吧！畢竟會對Open Data到底多少筆有感的朋友，當然是很多，但比起公車有感的朋友來講，可能是九牛一毛或者是百分之一的數字，所以如果用PTX當範例的話，讓大家比較有感覺，而且也能夠比較細的demo一些運輸型態的這一些東西，利用到OAS裡面比較多的功能，這個是非常好的具體建議，我們就這樣做。

另外一個是網址列上，其實這邊的version，其實它是有語意的，也就是當你更新一個spec或者是更新軟體package的時候，其實API version是可以賦予語意的，你會常常看到這個spec是3.0.0，如果未來只是做一些字樣上的調整、修正的話，也就是改最右邊的數字3.0.1。

如果是增加，而不是減少，如果本來使用者不會爛掉，而加一些新功能，也就是3.1.0，如果本來正在用的使用者會爛掉，就一定要叫做4.0.0，也就是有所謂語意的版本。

我們在寫規範的時候，有一個問題是，公部門大家還是比較習慣V1、V2、V3、V4的感覺，所以我們才會說給機器看的，也許有一些語意，但從使用者的角度來看，也許是第二版至第五版而已，但第四、五版加欄位，第五、六版中間是修bug，這個部分人不太需要知道這一件事。

但是對外我們去改version的時候，其實通常有兩個可能性，也就是從裡面的角度來看，也就是讓本來的使用者不能再接取了，好比在改V2、V3的時候，會給V2一個日落期，好比有兩年的時間，但是從此之後，斜線V2就不再回覆了，就到V3來。

另外一個是，本來的API是某個廠商，新版的廠商是完全另外一個廠商，而新的廠商說得很清楚，沒有辦法再支援舊的廠商API，然後就被它說服了，這時也會有兩版併行的情況，就是舊系統還在運行，而新系統是加到V3這邊來，即使這兩個不是完全不相容，但只有V3這邊會加新功能，這個也是有可能的。

這個其實不是很容易表示，因此我們才會在這個上面說對外、對內是兩個不同的表示法，對內是機器可讀的表示法也許可以用別的方式，又或者在說明欄位加change log都可以，但畢竟是給開發者看的，如果這些資訊都塞到網址列的話，大家不一定都看得懂。

如果逐漸棄用某一版的時候就說V2變V3，V2什麼時候落入，或者是新舊兩個廠商，V2是不會落日的，但是只有V3會加新功能，V2、V3併行，這些都可以，但是如果只是內部調降什麼東西，OAS的文件會改，但外面看起來，一直還是在V1。這樣可以理解嗎？

（點頭）

Sli.do：「想請問之後會針對openapi提供中央標準規範嗎（如包含欄位需求，定義等等）？想確定是否要等中央標準，再且廠商設計API，以免格式不被沿用。」

這個是有兩個的回答，分別是技術上跟政治上的回答，這個工並不可能白做，即使你現在做了一個盤點，發現你目前所提供的JSON API的欄位名稱叫cars，中央領域的Schema訂出來叫做vehicles，所以這邊v1變成v2了，欄位需要調校。

但做調校的工作，本來手上這一份是讓他好做非常多的，因為就可以指明OAS說這個欄位要變成這一個欄位，或者是這個欄位本來是三個選項，但要變成四個選項之類的，你可以就事論事去要求它，生一份更動說明書的時候，會錯意的機率非常低。

但是現在如果不做這一個盤點，等到另外一個領域的Schema下來的時候，那你要重新對齊，那是從頭做。

我的意思是我們把它想成是繞路好了，現在即使先做，並沒有真的繞遠路，而是在去的路上，可能不只十五度角，不會變成白做，而又要繞回去，會稍微繞一點，但我說整體來講是往整體的程序來走，這個是技術上的回答。

在政治上的回答是，當然國發會現在對於各種不同的領域，會定義這一個領域相關的資料集綱要，但是這一些資料綱要要如何訂？就是是看現在有誰已經把它做得還不錯了，跟別的利益關係人討論支援這個會不會有困難，所以越早做到這一個，就越有可能影響最後的即時大家要共通性的綱要，你越先做、要改的幅度就越小，是別人來抄你，並不是別人來抄你，我不會說每一個領域都是這樣，我也不是這樣的意思，而是有這一件事出現的話，現在先做比較有好處。

Sli.do：「今天所講的都是api的「說明文件」？」

你本來用什麼工具就用什麼工具，完全並沒有干擾你設計API的事情，這個是彼此不同的廠商、開發者非常好用的工具，但是內部要如何生出這一份東西來，完全是沒有規範的，因此這一件事，我覺得應該不會造成太大的負擔，只要不要把它寫成KPI。

有沒有其他想要討論的問題？一次、二次、三次，如果沒有的話，就非常感謝大家，有任何問題就讓國發會知道，謝謝大家。