Vultr API Design Suggestions

I went through your API and although it is working fine, you have not followed the industry's best method for creating a REST API.

For instance, I have realized you have a lot of resources/endpoints which could have been merged to a single endpoint where a developer should only tweak the HTTP method to make a call.

Your API uses a lot of verbs(doing word) than nouns(name of a thing) on the endpoint and this is not a good practice.

For instance, instead of an endpoint like https://api.vultr.com/v1/sshkey/create

You can create it like https://api.vultr.com/v1/sshkeys
and then, allow the developers to use POST for creating, PUT for updating and DELETE for deleting the keys.

For the users, instead of https://api.vultr.com/v1/user/create

You can just use https://api.vultr.com/v1/users to list with a GET method, then https://api.vultr.com/v1/users and POST for creating a user and https://api.vultr.com/v1/users with DELETE to create a user.


To list operating systems, just use https://api.vultr.com/v1/operating_systems with a GET method instead of https://api.vultr.com/v1/os/list

For the plans, you can just use https://api.vultr.com/v1/plans

Instead of https://api.vultr.com/v1/plans/list

For the servers, a user should just use the endpoint https://api.vultr.com/v1/servers to create(POST), Update(PUT) and Destroy(Delete). However, you have used a weird endpoint https://api.vultr.com/v1/server/list

Also, paging info, option to list only the required fields e.t.c should be available for those developing apps with limited space.

Also, it would be wise to separate the json elements displaying the main data with the rest of meta information as shown below:

{
"data": [
{
"contact_id": 1,
"contact_name": "MARY DOE"
},
{
"contact_id": 2,
"contact_name": "JANE ROEI"
},
{
"contact_id": 3,
"contact_name": "PETER ROE"
}
],
"meta": {
"count": 27,
"page": 1,
"per_page": 3,
"total_pages": 9
}
}

The above response format is cleaner and the API design I have suggested is very simple for developers to consume without lots of endpoints.

Yours faithfully,

Francis Ndungu

Comments

  • Hi Francis,

    Thanks for your feedback. We do have plans to improve on the API design in the future, and we'll review your feedback in our design discussion.
  • Great work in explaining it Francis!
Sign In or Register to comment.