RESTful API

Sanataro RESTful API

Authentication

You can chose one of the followings,

• OAuth2 (default: enabled)
• Basic Auth (default: disabled. not recommended because of personal information security)
• Session API (default: enabled)

The enabled/disabled can be changed in config/application.yml's api_auth section. (true: enabled, false: disabled)

Session Resource (when the API is used with techs such as Ajax in web browsers)

• This offer the authentication for WEB Browser to use session. When succeeded, response contains cookie. After creating a session, other resouces of API can be accessed with the cookie.
• You can access the resources via Basic Authentication or OAuth too. If you use either, You don't need this session resource. Skip this section.
• This is the single resource format. (URL is session, not session's')
• You need authenticity_token which is returned on creating session to update resources. (ie. POST, PUT, DELETE)
• to make session(login)
  • URL: api/session.json
  • Verb: POST
  • Presentation Format: JSON, URL encoded body.
  • Request Presentation Example

  { session: { "login": "USER_NAME", "password": "PASSWORD" } }

• Response Code
  • Authorized: OK (200)
    • with cookie
    • with the body: {"authenticity_token":"{TOKEN}"}
  • Unauthorized: Unauthorized (401)
• to delete session(logout)
  • URL: api/session.json
  • Verb: DELETE

Account

• Support: LIST ALL
• Authentication: "via api/session", "Basic Auth", "OAuth"
• URL: api/accounts.json
• Verb: GET
• Presentation Format: JSON
• Response Presentation Sample

{"accounts":[
  {"id":1,"name":"\u8ca1\u5e03","bgcolor":"faac3d","type":"Banking"}, 
  {"id":2,"name":"\u9280\u884cA","bgcolor":null,"type":"Banking"},
  {"id":3,"name":"\u9280\u884cB","bgcolor":null,"type":"Banking"},
  {"id":4,"name":"\u30af\u30ec\u30b8\u30c3\u30c8\u30ab\u30fc\u30c9","bgcolor":"e83b3b","type":"Banking"},
  {"id":5,"name":"\u7d66\u4e0e","bgcolor":"1acb0b","type":"Income"},
  {"id":6,"name":"\u8cde\u4e0e","bgcolor":"d91212","type":"Income"},
  {"id":7,"name":"\u96d1\u53ce\u5165","bgcolor":null,"type":"Income"},
  {"id":8,"name":"\u98df\u8cbb","bgcolor":null,"type":"Expense"},
  {"id":9,"name":"\u5149\u71b1\u8cbb","bgcolor":null,"type":"Expense"},
  {"id":10,"name":"\u4f4f\u5c45\u8cbb","bgcolor":null,"type":"Expense"},
  {"id":12,"name":"\u885b\u751f\u8cbb","bgcolor":null,"type":"Expense"},
  {"id":66,"name":"\u98f2\u307f\u4f1a","bgcolor":null,"type":"Expense"}
]}

Entry

• Support: LIST (monthly), Create, Update, Delete, Read
• Authentication: "via api/session", "Basic Auth", "OAuth"
• URL: api/entries.json, api/entries/10.json (10 is entry's ID)
• LIST's Acceptable URL params: year, month, tag, mark
  • When URL params are not specified for LIST, the response is the list for the current month
• Presentation Format: JSON
• Presentation format example for "GET api/entries/103.json"

{"entry": {
    "id":103,
    "name":"master\u304cRESTful API\u306b\u5bfe\u5fdc\u3057\u307e\u3057\u305f:ok_woman:",
    "from_account_id":1,
    "to_account_id":8,
    "action_date":"2012-10-18",
    "amount":3000,
    "adjustment_amount":0,
    "tag_list":"" }}

• FOR Create, Update, Delete
  • The response of these requests contains not only the entry itself but the entries as follows,
    • The response of Create, Update and Delete includes "updated_entry_ids", which is the array of entries' id which has been updated simultaniously by the request.
    • The response of Delete includes "deleted_entry_ids", which is the array of entries' id which has been deleted simultaniously by the DELETE request.