Understanding REST at Enercon
Enercon is thrilled to introduce you to the world of REST (Representational
State Transfer). REST is a fundamental aspect of Enercon services that ensures
efficient communication between your applications and Enercon systems.
What is REST?
REST is an architectural style for designing networked applications, emphasizing
simplicity, scalability, and a stateless communication model. At Enercon, we
leverage RESTful principles to provide a seamless and reliable experience for
our customers.
How We Use REST API
At the core of Enercon services is the use of REST APIs (Application Programming
Interfaces). These APIs enable your applications to interact with our systems,
allowing you to access and manipulate data effortlessly. REST APIs use standard
HTTP methods such as GET, POST, PUT, and DELETE.
JSON Format: The Language of Communication
REST utilizes JSON (JavaScript Object Notation) which acts as a universal
language. All requests and responses are structured in JSON format, a
lightweight data interchange format that is both human-readable and
machine-friendly. This standardized approach ensures clear and consistent
communication between your applications and our servers.
Decoding Status Codes
When making requests to our REST API, it’s essential to pay attention to the
HTTP status codes returned. A status code in the range of 200 to 299 indicates a
successful operation, and you can expect a custom data object in the response.
This data object will contain the information you requested or the result of the
operation. Status codes outside this range signal an error. Status codes in the
range of 400 to 499 indicate an issue with your request and status codes in the
range of 500 to 599 indicate an error on Enercon’s end. For errors, you can
expect a standard error object in the response. This object will provide details
about what went wrong, helping you troubleshoot and resolve issues efficiently.
Example Request
POST
- We need to create a JSON body to go in this request, we can find the
structure of this JSON using the Swagger documentation. - To get what parameters are required and a brief description of each you can
click the Schema tab of the request body section. All parameters with a red
star next to their name are required. - Using the URL from the Swagger page along with the endpoint named in this
section we can construct the full URL.
http://enerconapi/datalogging/FunctionalTest/Start - Create the body to reflect the example with your own data.
- Send the request.
Handling the Response
As stated previously the responses fall into one of three buckets 200 to 299
indicates a successful request, 400 to 499 indicates a client error and 500 to
599 indicates a server error. In terms of response structures, there are only
two groups, valid response object and error response object. The valid response
object is not the same for every request but the object for the error is always
the same across all Enercon APIs. When an error response is received it is to be
assumed that no data made it into any Enercon system, and the request should be
attempted again.
Good Response
Here is a good response that has returned data that you can parse and use as you
need.
Bad Response
Here is a bad response. This returns the error code, error, error message and
traceId. If there is any interface to the user, the message should be displayed
to provide them context to the issue.
