Getting started

Start testing your requests

Once you have received your access information, you can start making requests using test endpoints, https://pre-api.iryo.eu.

Servers behind these endpoints are fir testing purposes meaning that any booking requests or payments using them will not result in real
service booking or credit card charges, then you can test all funcionalities available.

You can find information related with our services and different structures involved at Swagger specifications , also it is possible to fork our
postman collection in order to start calling our API:

 Run in Postman

When using Postman, you need to include this environment:

PRE - Iryo Con… nt.json

09 ago 2024, 08:38 pm

Composing an Iryo Conecta API request

Headers

Headers represent the meta-data associated with an API request and response. They carry information for the request and response body,
the request authorisation, and response caching and cookies. For each request, headers must be set correctly by using a key-value pair.

Each request to Iryo Conecta API will include a set of headers, these are the headers managed by our Api:

Key Value Description

Content-Type Required application/json Indicates that the request body format is JSON.

Accept Required application/json Sets output type to JSON.

Accept-Encoding Required gzip Returns compressed results with GNU .ZIP format. Must be
included at availability and queries Services.

Authorization Optional Bearer {{auth.token}} Authorization takes place within the headers of each HTTP
request. An Authorization header should be send with each
request. Need to be included at every request excepts
authorisation and master data services. (see Autenticatio
n / Authorization process to know how to obtain an
authorization token)

Accept-Language Optional {{locale}} Indicates the natural language and locale that the client
prefers.

Ocp-Apim- Required {{suscription.key}} Subscription key, required to be included in all the requests
Subscription-Key to our API
  Important!

Please note that the API key and Subscription key you have recieved with registration only give you access to our test/ evaluation environment,
once your development has been completed and validated from Iryo side we will send you those keys for live environment use.
API key and Subscription key are your access credentials to our systems, you should take all necessary and appropriate measures to prevent to be
obtained and/or used by anyone else. If you lose these keys or you suspect someone non authorized has accessed to them, please, request for new
ones at our Help Desk

When access is granted, the language is set and the content-type is defined, then a request header will look similar to this example:

1 GET /conecta/availiability/search HTTP/1.1

2 Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICItR1lzcE1TY3BBNWwxUERrYVZNSDBXNVZnd0dkZGp
3 Accept-Language: en-GB
4 Content-Type: application/json
5 Accept: application/json
6 Accept-Encoding: gzip
7 Ocp-Apim-Subscription-Key: ca76fc6d3f83443b808bda61233007e9

Type of operations (method)

All operations in the JSON API are based on the HTTP request methods of "GET", "PUT", "POST", "PATCH", "DELETE" and "HEAD", using
the HTTPS protocol. Each of these operations are split in a Request and Response message, although some GET operations do not send
in a specific request. For these, by definition, the instruction on which information should be retrieved is based on the URL of the operation
itself.

Request: URL

Each Iryo Conecta API request, requires a dedicated URL that represents the API endpoint, also referred to as location or route. All URLs
have a base that is completed with a path,
e.g. https://api.test.iryo.eu/conecta/manage/bookings/{{booking_number}}/passengers/{{passenger_id}}

https://api.test.iryo.eu = base URL (referred to as ‘host’);

/conecta/manage/bookings/{{booking_number}}/passengers/{{passenger_id}} = path.

One location can provide more than one endpoint when various methods are accepted. For instance, GET Passengers provides an
overview of the passenger's information set in a particular booking and PATCH passengers will create a new passenger to that booking.

Some endpoints require users to put in a variable: e.g. /conecta/manage/bookings/{{booking_number}}/passengers/{{passenger_id}}.

Variables are unique components to an endpoint and depend on the information that was configured. In this case, the booking_number
variable set the booking and the passenger_id variable the passenger we want to handle. The complete endpoint for logging out passenger
information may look like this:

https://api.test.iryo.eu/conecta/manage/bookings/85AM7JFO/passengers/passenger_1

When using the URL field, query parameters can be sent. Query parameters are appended to the end of the URL, following a ? and listed in
key-value pairs, separated by &.

Example: /conecta/manage/bookings/search?origin=60000&destination=71801.

Request: body

Whenever there is structured data that needs to be added or adjusted, as is the case with a PUT, PATCH and POST request, body data is
sent. For instance, there is data stored about a passenger, but that person's email address needs to be updated. In the request that is sent
to update the database, the email address will be included in JSON and the method used will be PUT or PATCH. Please note: when sending
body data, headers such as content type are important to ensure that the API can correctly process the received data.

Example of POST Journey Search

 1 OST https://api.test.iryo.eu/conecta/availability/search HTTP/1.1
2 Accept-Encoding: gzip,deflate
3 Content-Type: application/json;charset=UTF-8
4 Accept: application/json
5 Accept-Language: es-ES
6 Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICItR1lzcE1TY3BBNWwxUERrYVZNSDBXNVZnd0dkZG
7 Content-Length: 358
8 Host: api.test.iryo.eu
9 Connection: Keep-Alive
10 User-Agent: Apache-HttpClient/4.5.5 (Java/12.0.1)
11
12 {
13 "currency": "EUR",
14 "passengers": [
15 {
16 "type": "AD",
17 "id": "passenger_1"
18 }
19 ],
20 "travels": [
21 {
22 "id": "travel_1",
23 "origin": "6000",
24 "destination": "71801",
25 "direction": "outbound",
26 "departure": "2022-01-07"
27 }
28 ]
29 }

Trace header

Every response includes an specific header named b3 standardized in late 2018 for use in JMS and w3c tracestate, this header must be
included when you open a bug issue at our Help Desk, here you can find an example:

1 HTTP/1.1 200 OK
2 Cache-Control: no-cache, no-store, max-age=0, must-revalidate
3 Keep-Alive: timeout=60
4 Pragma: no-cache
5 Transfer-Encoding: chunked
6 Content-Type: application/json
7 Expires: 0
8 Vary: Access-Control-Request-Headers
9 X-Content-Type-Options: nosniff
10 X-XSS-Protection: 1; mode=block
11 b3:b87fbfa70a4bcbccafa03a57a0c23bde-474097949873549c
12 Strict-Transport-Security: max-age=31536000 ; includeSubDomains
13 X-Frame-Options: DENY
14 Date: Thu, 13 Jan 2022 06:33:50 GMT
15
16 {"data":[{"name":"Barcelona-Sants","shortCode":"YJB","uicStationCode":"71801","timezone":"Europe/Madrid","connec