Have a good ReSTful API

  • Define resources, design URL address. When we design the endpoint address for the ReSTful interface, the way how we access the resources dictates the design of the endpoint URLs.
  • ReST on HTTP. Building the ReSTful API on HTTP becomes the de facto standard nowadays. An HTTP based API requires proper usage of HTTP methods, HTTP mime types, and HTTP error codes.
  • Let the ReSTful API talk. Make the ReSTful API self-explainable and navigatable.
  • Implementation of ReSTful API. YAML, entities/DTO/VO, and more.

Define resources, design URL address

  • What kind of resource we are exposing to the client?
  • How we are going to organize the resources?
  • How are we going to versioning the API
  • Versioning using the URL. Currently, versioning with URL is widely adopted. I have seen two approaches.
  • Versioning using the HTTP header by adding a new HTTP header to indicate the API version
  • Versioning using the entity field, be it JSON or other formats.

ReST on HTTP

  • To get all entities:
  • To get the entities with query criteria:
  • To get the details of a single entity by ID:
  • Successful POST returns 201 Createdresponse code with the created entity as the payload (The ID of the created entity should be in the payload).
  • Failure POST due to the entity with the same ID already exists returns 418 I'm a teapotresponse code (I am just kidding). Please return 409 Conflictresponse code instead (no kidding).
  • Failure POST due to the incorrect JSON format in the request returns 400 Bad Requestresponse code.
  • Failure POST due to server resources are not available, for example, database connection down, returns 500 Internal Server Errorresponse code.
  • Successful PUT returns 200 OKresponse code with the created or updated entity as the payload.
  • Failure due to the incorrect JSON format in the request returns 400 Bad Requestresponse code.
  • Failure due to server-side errors, for example, database connection down, returns 500 Internal Server Errorresponse code.
  • Successful DELETE returns 204 No Content response code with no content.
  • Failure due to the resource with the specified ID can’t be found returns 404 Not Found response code.
  • Failure due to server-side errors, for example, database connection down, returns 500 Internal Server Errorresponse code.

Let the ReSTful API talk

  • ID: id of the entity
  • Name: name of the entity
  • Description: description of the entity
  • The response of getting all entities API provides the links for API to access a single entity.
  • The response of a single entity API provides the link to return back to get all entities API.

Implementation of ReSTful API

  • API package: package for generated API classes, which are the ReST API endpoint-entry-classes. Meaning, the ReST requests will be handled by the classes from this package. In the generated package, the API classes shouldn’t be touched, while the controller classes should be filled with your own code.
  • Model package: package for generated models, which are the model objects/entities defined in definition section of YAML file. The generated model is actually the data model for the ReSTful interface. It reflects the internal data model, but not necessarily the same as the internal data model, so it also provides a layer of abstraction to protect the internal data model.
  • Invoker package: root package for generated code, which also serves as the basePackages for the Spring ComponentScan annotation. All classes under this package with Spring annotation such as Component or Service etc. will be picked up by the Spring and be available in the Spring application context.

--

--

--

Life is beautiful…

Love podcasts or audiobooks? Learn on the go with our new app.

Recommended from Medium

Laptop Stuck on Preparing Automatic Repair during Startup (SOLVED)

Ktor: another boring HTTP framework? Part 1

Kubernetes is complex; scare-mongering or reality?

On A Journey through Open Source

Vulnhub-DC 3

Django’s views

Building JS-Rails-API Project

A Closer Look at Redis Dictionary Implementation Internals

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store
Tom Liu

Tom Liu

Life is beautiful…

More from Medium

TVS ERC-20 and ERC-721

A simple step by step guide for installing and using the Epic Cash Server and CLI wallet.

CS371p Spring 2022 Week 14: Mueed Ahmad

How to resolve PHP has encountered an Access Violation