There are many companies provide services using RESTful API server which may exposed to external customers/subscribers or for their company internal interconnection in multi servers which located in different locations (VPS or cloud). There are a few variants (ways) of implementing a RESTful API, some implementations are really following the recommendation which stated in Representational State Transfer (REST) (another good read is this restfulapi.net).
So what is RESTful API server? It is an API server which use HTTP protocol and using HTTP methods in REST architectural style, so it is just a style (a set of rules or constraints), there is no official specification. The RESTful API server uses HTTP methods to accomplish CRUD (Create-Read-Update-Delete) commands.
| Action | HTTP method |
Example |
|---|---|---|
| Create a new record | POST | https://example.com/product/
* the data content will be defined in the request body normally in JSON text or an http form-data |
| Read a record or get list | GET | get a product: https://example.com/product/123456 get product list by search a fixed formatted URL (eg: category and color): https://example.com/product/shoe/red get product list by search by a dynamic query: https://example.com/product/search?category=shoe&color=red&price-from=10&price-to=99 |
| Update a record | PUT (or PATCH) |
https://example.com/product/123456
* the new record data will be defined in request body normally the same like in POST to create a new record. |
| Delete a record | DELETE | https://example.com/product/123456 |
In either POST or PUT request, we need to send some data and we have to set the 'Content-Type' in request header to define what is the format (type) of our data
- multipart/form-data : for submit form or for upload file.
- application/x-www-form-urlencoded : multiple keys-values pairs query.
- text/plain : just plain text with whatever format we want.
- application/json : JSON validated text content.
So is RESTful API is good? I think the major reason people using RESTful API is because the old way to achieve client-server communication or server-to-server interconnections is using SOAP which in these days considered as obsoleted and trouble-some to implement due to the need to use extra library requirements to manage complex XML. So comparing SOAP to RESTful, RESTful is better and more modern.
Many developers are saying they use RESTful API server, but in fact are using only 2 most commonly used HTTP methods (i.e.: GET and POST), some people call it REST-like, but they should not call it anything with the word 'REST' at all, instead they should call it just plain API server.
So which is better? RESTful API server or plain API server? personally I recommend to use plain API server.
My own experiences involved in developing some API servers are mostly using GET and POST method only, the actual CRUD commands in the URL (for verbose, easy development and allow browser cache) and the parameters (data) are inside request body, APIs examples in eCommerce service, get a product detail (GET: https://api.example.com/index.php?action=get&product=123456), create a new product (POST: https://api.example.com/index.php?action=create&item=product) with product detail data inside the request body (as JSON).
What is the benefit of using GET and POST methods only compare to using many other HTTP methods like RESTful?
- Easier to code only to handle GET and POST instead of handling many methods including PUT, PATCH, DELETE
- For some business requirements, such as searching for records may need to define many parameters which if using GET will make very long URL (irritating to see and not easy to read)
- To increase security, some implementations of API servers are only using a single URL with only HTTP POST method,
commands and parameters are defined in request body,
this will increase security by avoiding hacker to see the URL addresses and to avoid browser to cache URL addresses.
* Using HTTPS (with less than TLS 1.3) will only encrypt the request body (content), the URL will be sent in clear.
* At this time of writing, only if using TLS 1.3 with encrypted SNI can encrypt URL.
Whatever we choose, RESTful API server or just plain API server, it is recommended to have security features to avoid our API server being abused.
- URLs (end-point) use HTTPS
- Need to login manually to get authorized token/cookie or use private key as identification and to encrypt data
- Every API call (request) need to have some sort-of secure token in HTTP header (such as: 'Authorization') or cookie, without this then API server should ignore this call (return 401 Unauthorized) and DO NOT send detail respond about what is wrong.
- Secure token or cookie must have EXPIRE TIME, normally 30 minutes since last access (updated regularly), to avoid middle-man attack in the future.
- API server need to have LOGGING feature to record activities of WHO (user), WHERE (from IP address / location), WHAT (detail action) and WHEN (time).