开 api 日常心得笔记

开 api 规格是个有趣的事情，从栏位命名、资料阶层设计、易读性、合理性、方便性都是需要考量的点，对於BE来说，开api规格就像是在推出一件产品，而使用者是前端夥伴，我们都接过很鸟的api，所以自己会希望自己开出来的规格是尽量能够适应变化，又给前端有好使用体验的api

api 结构设计

目的导向：方便写入DB vs. 易读易理解的结构

这是最近任务做Patch API 带来的启发，过往在更新资料时，我会希望api req 尽可能与DB schema 相同，这样我可以省下从req 撷取相关栏位组成需要储存资料的过程，不过这样的情况比较适合成熟稳定、不易变动的需求，因为每当遇到变动需求，我就需要重新调整 api req 规格，造成FE 多出相关成本来适应这场变动，只因为我想要可以不需要有资料撷取的动作．

那麽好的方式是什麽呢？
我认为是，复杂度较高的Patch Api (ex.超过一个阶层的req Object)，应该以易读易理解的结构为目标，让FE可以快速理解，相关资料应该放到哪些物件中，而非一个规格适应不同规格，只因为可以直接存进去ＤＢ，这样带来的好处是，如果需求有所变动，FE 可以只针对变动部分调整，而省下因为相依性带来变动成本

api 易读性标注

新手时开api 只觉得，阿我给你栏位名称就好，後来开始知道最好还标上型别，再後来知道有enum栏位最好也写上enum，栏位命名精准好理解，也能帮助api串接正常，

後来了解到，写的越清楚，可以省下不必要的沟通成本，让开发者都好好专心开发，不过开发时间总会有时间压力，究竟要写得多完整是可以取舍的，但长期来说，我还是会期待自己可以有效的运用时间，开出一份尽可能适应变动、易读易理解的好规格，让串接我开的api的FE夥伴可以有愉快的串接经验，我只能说我还在往这条更好的路上迈进，可能还不够好，但是会越来越好der