Oracle APEX and RESTful API standards
Web services guidelines
Consistent RESTFul APIs
For the past few month I have been involved in corporate level interoperability project and these are my few key "lessons-learned" notes.
We know and we have all heard of RESTful services and how important they are today for any production systems that are exchanging data.
Point here is to emphasize importance of having standards to provide guidelines for architects and developers in the design and development of RESTful APIs that are consistent, usable, max reusable and are based on current industry best practices.
Similar to your PL/SQL and Oracle APEX standards these are things that will evolve over time but key thing is to consider having them before development work begins.These guidelines are applicable regardless if your services are built with Oracle APEX, PHP or any other technology.
I will try to keep short and sweet as I am sure a lot can be said on this topic.
Overall summary would be:
REST Guidelines Summary
|
A REST URI identifies a resource
|
REST URIs should include nouns, not verbs
|
Use plural nouns to represent resources for consistency (no singular nouns)
|
Use HTTP verbs (GET, POST, PUT, DELETE) to operate on resource collections and elements
|
Use HTTP headers to include meta-data where possible
|
Use the correct HTTP status codes for responses
|
Control the depth and try not to nest deeper than /resource/{id}/resource if possible
|
Version the API using major, minor and patch version numbers, e.g. v1.0.0
|
Put the major version number in the URI, prepended with a ‘v’, for example https://my-resturl.com/v1/resource
|
Develop services that are idempotent, i.e. (accidentally) invoking the service twice with an identical payload has no undesirable side effects
|
Handle concurrency for 'unsafe' methods (i.e. PUT, POST, DELETE) where required
|
Default on using the JSON format for request and response messages
|
Use lowerCamelCase JSON message formats
|
All incoming and outgoing dates and times comply with the ISO8601 standard
|
All dates and times returned by a service should use the following ISO8601 compliant UTC common format: YYYY-MM-DDThh:mm:ss.sssZ
|
Wrap responses and error messages using a standardised format
|
Use the Common Information Model (CIM) where available
|
Always use HTTPS to secure the API at the transport layer
|
< Use OAuth 2.0 for token based security
|
Never change service features that have been released
|
As a consumer of a REST service: ignore content that is not used
|
Global guidelines
Design before build - The desired behavior of the API,
including endpoints and message examples, must be designed, documented and
reviewed before implementation starts.
OpenAPI specification - APIs must be specified using the OpenAPI Specification which is a well-established and widely adopted standard that allows both humans and computers to understand the capabilities of a service, without having to access the source code.
Include
the major version number in the URI
- The major version should be prepended with the letter ‘v’ to form the URI as
it improves 'explorability' via a browser address bar:
https://my-resturl.com/v1/projects
Use plural nouns for resource names - This makes interfaces more intuitive to use and avoids having to
deal with unusual pluralisation, such as diagnosis/diagnoses
/employee
/diagnoses/1234
Use hyphens in URIs for resource names
that consist of multiple words
/v1/employee-profile
Use lowerCamelCase for URI query parameters - This
is consistent with the default notation for JSON messages
/projects/1234?select=name,startDate,finishDate
Avoid using verbs in resource names - it may be convenient to use a verb to indicate a status change of
a resource. The following URI may be implemented to activate a project:
POST
/projects/1234/activate
Don’t use verbs in the URI
for CRUD-type operations, e.g.:
Incorrect:
GET
/GetAllProjects
Correct:
Resource
|
Expected Behaviour
|
GET /projects
|
Retrieve a list of
projects
|
POST /projects
|
Create a new project
|
PUT /projects
|
Bulk update complete
project records
|
PATCH /projects
|
Bulk update partial
project records
|
DELETE /projects
|
Delete all projects
|
GET /projects/1234
|
Retrieve a specific
project
|
POST /projects/1234
|
Usually invalid, but
may be used when the consumer is allowed to provide the primary ID in a
create resource request
|
PUT /projects/1234
|
Update all
attributes of a specific project
|
PATCH /projects/1234
|
Update one or more
attributes of a specific project
|
DELETE /projects/1234
|
Delete a specific
project
|
Use the appropriate HTTP status codes to indicate Success and Failure
Implemented services in such a way that they are idempotent -
multiple requests to a service with an
identical payload have no adverse effects to the overall state of the resource.
Detect concurrent modifications - Unsafe
methods (i.e. methods changing resources) must consider the need to detect
concurrent modifications. A common way to implement this is to have a read
(GET) operation on the resource include an HTTP ETag header containing a digest
(hash, e.g. MD5) representing the state of the resource.
Message format defaults to JSON
- JSON is more lightweight than XML and just as easy for humans to understand.
In addition, no parsing is required by JavaScript clients to use JSON messages.
Do not store values in keys of a JSON object
Correct:
{
"gender": [
{ "code":
"M", "description": "Male" }
]
}
Empty fields - Empty fields in response messages should be included as
null instead of being omitted.
Timestamps
- All timestamps
accepted and returned by the service ideally must be in ISO 8601 format [5]
with time zone information.
Validate all input fields - basic check like i.e. required and unique parameter, string, number types or follows certain pattern
Restrict usage of wildcards - for performance; check if at least one parameter is supplied
Collection of data
Enable
pagination of collections by using the standard keywords ‘limit’ and ‘offset’.
Define
an appropriate default limit that makes to prevent unnecessary use of bandwidth
and resources.
Use
the standard keyword ‘sort’ to indicate sorting of collections. Use ‘+’ to
indicate ascending sort direction, use ‘-‘ to indicate descending sort
direction. If no direction is specified, the default sort direction should be
ascending.
Error
messages
Must include the following
information:
·
a HTTP status code;
·
a link to the resource causing the
error;
·
a short error message;
·
a longer description explaining the
cause of the error.
Avoid exposing detailed system log messages to the consumers on production systems.
Security
All REST services should be exposed through the HTTPS
protocol to provide security at the transport layer.
Services should use OAuth 2.0 to support token based
authentication.
API
designers and developers should avoid exposing sensitive information like user
names, API keys, security tokens or other credentials on the URI.
It
is not enough to rely on consumers of the service to validate the input of
end-users. The API is responsible for checking that the data provided in the
service request conforms to business rules and does not pose a threat from a
security perspective (e.g. SQL and NoSQL injection, Cross Site Scripting).
REST services, particularly
services that are exposed to the public, must be monitored using an API
Management Tool
Conclusion:
Luckily once we have all of this in place APEX makes it easy to consume your newly created APIs. To make your life easier check out REST Client assistant packaged app and start from here. :)
Happy APEXing
SLino
