🎏 SemanticApi是一個可以幫助你簡潔有力的宣告 URL 以及更好地使用 API的工具。( <1kb )
還記得我們是怎麼跟各種API網址鬥智鬥勇的嗎? 從最初的 字串拼接 到ES6的 模板字串,抽出去到config.json
也好,放一些特殊字串如%ID%
然後再replace
等等的方法...
SemanticApi提供一個簡潔有力的方法來宣告 URL 與使用 API,下面舉幾個對比栗子。
const baseUrl = 'https://api.example.com/'
const options = { page: 2 }
const ex1 = baseUrl + "v4/user/" + UserID + "/filter?page=" + options.page
const ex2 = `${baseUrl}v4/user/${UserID}/filter?page=${options.page}`
// ====================================================================
const ex3 = SemanticApi(baseUrl).v4.user(UserID).filter.query(options)
// ====================================================================
// => https://api.example.com/v4/user/9527/filter?page=2
SemanticApi 支援 Node.js
8.0
以上,以及Chrome/FF/Safari (NO IE)的最新版本。
由於利用了ES6 Proxy 的特性 ( CanIUse ),目前沒有任何可行的降級/Polyfill方案 (未來應該也不會有)
Node.js
>= 8.0
npm install semantic-api --save
- 從 /dist 下載打包好的檔案
import SemanticApi from 'semantic-api'
console.log(SemanticApi().try.to.test.api)
// => "try/to/test/api"
console.log(SemanticApi('/').user.id(9527).profile)
// => "/user/id/9527/profile"
建議在 SemanticApi 外多封裝一層以便清晰的表達其意圖。
import SemanticApi from 'semantic-api'
const API = {
get spotify () {
return SemanticApi('https://api.spotify.com/')
}
}
API.spotify.music.category(7).filter.query({ premium: true })
// => https://api.spotify.com/music/category/7/filter?premium=true
你可以綁定一些像是 fetch
, axios 等HTTP庫來實現更方便的鍊式調用。
import SemanticApi from 'semantic-api'
class Instagram {
static get api () {
const baseUrl = 'https://api.instagram.com/'
const customFn = {
get: function (args, calls, url) { ... },
post: function (args, calls, url) {
return fetch(url, args.shift(), { method: 'post', ... })
}
}
return SemanticApi(baseUrl, customFn)
}
static login (data) {
const options = { client_id: 'CLIENT-ID', redirect_uri: 'REDIRECT-URI' }
Instagram.api.oauth.authorize.query(options).post(data)
.then(...)
}
}
Instagram.login(...)
// POST https://api.instagram.com/oauth/authorize?client_id=CLIENT-ID&redirect_uri=REDIRECT-URI
類型: string
預設值: ""
類型: object
預設值: {}
幾顆栗子:
SemanticApi().api.user(9527).test.fnName(123, '456')
customMethods = {
fnName: function (args, calls, url) {
// args 是一個參數array. Ex: [123, '456']
// calls 是前面chaining call的紀錄. Ex: ['api', 'user', 9527, 'test']
// url 是當前組合完成的Url. Ex: 'api/user/9527/test'
// 可以與calls進行互動,push() pop()都會應用到semanticAPI內部
calls.push('anotherFnName')
// `return` 會立刻停止鍊式調用並返回該值
return fetch(url, options)
}
}
類型: object
注意: data
不接受Nested object,僅能處理一般的單層object.
如有需要,隨時可以透過 customMethods
來override舊有方法.
const obj = { name: 'bob', age: 16, test: true }
SemanticApi().query(obj)
// => ?name=bob&age=16&test=true
- Inspired by Discord.js