Skip to main content

Introduction

docs image

EVA developer 101

What you need to know before touching Core

Any operation in EVA is essentially just a simple message that's sent to EVA Core, which then sends a response. In this introduction, we will be sending out our first request and explaining some things along the way.

Endpoint

First off, we need an EVA environment we can send the message to. This environment is represented by a certain endpoint. Endpoints are customer specific but generally look something like:

  • https://api.xxxxxxx.eva-online.cloud

EVA includes a shit ton of services, somewhere upwards of 1700. When making a request using any of these messages, we should specify what message we are actually trying to send. To do so, we will suffix this specification to our endpoint. For example, a simple product search request would be sent to:

  • https://api.xxxxxxx.eva-online.cloud/message/ping

Message

Now for the actual message. You can call EVA with a simple HTTPS POST message with JSON serialized content, using TLS 1.2 or above.

For our first ever message, we will be calling the Ping service. This service accepts an empty body:

POST https://api.xxxxxxx.eva-online.cloud/message/ping
{}

There's just one thing we are missing. Well, actually two things.

Headers

Before we can make our first request, we have two include the two headers that are mandatory in EVA;

Header NameValue
EVA-User-AgentIdentifier for the application you're sending the message from. E.g. ApplicationName/1.0.
Content-TypeThe value for this should be application/json to indicate we are sending JSON content.

Additionally, we need certain headers and correct authentication.

First request

Now that everything is in place for our first request, we can send it out:

POST https://api.xxxxxxx.eva-online.cloud/message/ping
{}

We will get the following response:

{
"Error": {
"Message": "You are not authorized to execute this request.",
"Type": "Forbidden",
"Code": "BBHSOCV",
"RequestID": "2b8ed8f38df23d1dd651923f3e7bdd8f"
}
}

We get this response, because we do not have the proper authorization to perform this request. The request in itself was correct, we just haven't authenticated ourselves. We have of course totally intentionally set you up with a request that requires authentication so we could grasp your attention for our next subject; Authentication. Surprise.

Authentication

Even though some services can be called without authentication, most of the time it is mandatory to authenticate yourself. We authenticate ourselves by providing a token in the Authentication header. Read the Authentication documentation to find out how to acquire a token.

Changes

Requests and responses may gain additional properties without prior notice!

EVA will include a EVA-Warning header with details on calls that are not optimal - you may be using a deprecated service, missing a certain property, using an inefficient property, or anything else suboptimal. Warnings will turn into actual errors later, so you should catch this response header and follow up on them to ensure a continued operation.