How to design the interface elegantly

Posted on

There are many factors we have to consider during disigning an interface, this blog will discuss these factors in regular and irregular ways.

Foreword

There are many factors we have to consider during disigning an interface like these:

  • Business positioning
  • Security
  • Scalability
  • Stability
  • Cross-domain
  • Protocol
  • Routing
  • Single responsibility
  • Filter & Combination

This blog will try to analysis these factors.

Regular

1. Responsibility

It must be clear that what is the responsibility of an interface, what business problem does it solve.

2. Single

One interface, one duty. A lot of designer thought that more is better, but it will cost a lot more when you try to extend your system. Jobs told us, less is more.

3. Protocol

The interface would use what protocol depend on the situation:

  • FTP : when you need transfer files
  • HTTP: the data you send through this interface is not sensitive, low security requirement
  • HTTPS: HTTP + SSL, sensitive data, high security requirement

4. Routing

API represents resource, so basicly we use more nons and less verbs:
/api/v1.0/Product/2019
/api/v1.0/Users/2019

5. Request methods

  • Get /users: list all users
  • Get /users/id: get user by id
  • Post /user: new user
  • Put /user/id: alter user by id
  • Delete /user/id: delete user by id

6. Domain

There are main domain and business domain, main domain can be used for the API that will not change for a long time, business domain can be used for the specific area. For example:

  • google.com: main domain
  • play.google.com: business domain

7. Cross-domain

After domain name has been determined, we must consider the cross-domain problem, and use what kind of methods:

  • JSONP
  • CORS
  • window.name + iframe
  • window.postMessage()
  • change document.domain for sub domain
  • Websocket
  • Proxy

8. API version

Sometimes we should add version in the url: http://api.demo.com/v{d}/, like this :
/api/v1.0/Pruducts/2019 list all products in 2019 with version number 1.0

9. Filter

We should add some condition filter when the size of records is huge, like : top, page, group, sort, where.
Here is some examples:

  • ?limit=100 : return 100 records
  • ?offset=101: return from num 101 records
  • ?page=10 : page num 10
    per_page=100: 100 records per page
  • ?sortby=name
  • ?order=desc
  • group=groupname
  • product_type=1

10. Data format

  • Failed

    1
    2
    3
    4
    5
    {
        "status":0,// 0-failed，1-succeed
        "error_code":"2003",
        "error_des":"Authentication failed"
    }

  • Succeed 

    1
    2
    3
    4
    5
    6
    7
    8
    9
    {
        "sid":"jc20190816",//token id
        "users":{
            "id":"jc201908162354",
            "name":"Jincheng-Jason",
            "addr":"Auckland"
        },
        "status":1
    }

11. Robustness

Security, Concurrency, Anti-attack, Cross-domain etc.

12. Scalability

13. Permission

14. Status code or return code

Irregular

Sometimes one single interface has to return the data from other several APIs.

1. Request

1
2
3
4
data:[
    {url:'api1',type:'get',data:{...}},
    {url:'api2',type:'get',data:{...}},
]

2. Response

1
2
3
4
5
6
7
8
{
    status:0,
    msg:'',
    data:[
        {status:1,msg:'',data:[]},
        {status:1,msg:'',data:{}}
    ]
}