Quick API Reference

Here are the APIs associated with ETX.

RegistrationCopy Anchor Link

The Edge Transportation Exchange (ETX) Registration APIs allow ETX users to register themselves as vendors, register their devices or software services, and request the connection endpoint in order to connect to the ETX system.

In order to use the APIs the user needs to have a ThingSpace account and use their ThingSpace credential to request an Access/Bearer token, which is used to authorize the user, and also request a Session/M2M token to authenticate the user.

• For details on how to obtain the token please refer to the ThingSpace Quick Start Guide - Obtaining an Access Token.
• For detail on how to obtain a Session/M2M token please refer to the ThingSpace Quick Start Guide - Obtaining a VZ-M2M Session Token Programmatically.
• Or watch the ThingSpace API Video Guide 1 and ThingSpace API Video Guide 2 that explains how to obtain both tokens.

When users want to utilize ETX, they have to go through 3 steps:

1. Call the clients/registration endpoint to request a device ID and certificate package. This ID and certificate will be needed to connect to the ETX Message Exchange through MQTT.
2. Call the connection endpoint to request the MQTT URL for the ETX Message Exchange. This request will provide the right MQTT endpoint based on client location and network connection type.
3. Use the credentials to create an MQTT connection to the URL received from the connection endpoint and start using the system.

Map Data ManagerCopy Anchor Link

The Map Data Manager is the intersection metadata storage & management service within the Edge Transportation Exchange (ETX).

It allows users to upload and download SAE J2735 MAP messages in ASN.1 UPER or JER format.

In order to use the APIs the user needs to have a ThingSpace account and use their ThingSpace credential to request an Access/Bearer token, which is used to authorize the user, and also request a Session/M2M token to authenticate the user.

• For details on how to obtain the token please refer to the ThingSpace Quick Start Guide - Obtaining an Access Token.
• For detail on how to obtain a Session/M2M token please refer to the ThingSpace Quick Start Guide - Obtaining a VZ-M2M Session Token Programmatically.
• Or watch the ThingSpace API Video Guide 1 and ThingSpace API Video Guide 2 that explains how to obtain both tokens.

Access Control ConfigCopy Anchor Link

The Edge Transportation Exchange (ETX) - Access Control Configuration Service is responsible for managing the access rules (ACL rules) for the ETX message exchange layer. These roles are used to define which part of the ETX system the devices and applications are authorized to use. The ETX message exchange layer is based on MQTT, so the roles defined in the config service are used to determine which topics the devices and applications can publish or subscribe. It also defines how many subscriptions each application or device can create and how fast they can publish messages to the system. The access rules are defined as the following:

• Rule Name: The unique name of the access rule. The rule name can contain variable such as ${clientType} or ${clientSubtype}, which than can be used in the subscription or publish topic names. If these variable are used it means that the client type or subtype used during the client registration process will be applied in the rule. For Example: If the rule name is ts.device.mqtt.imp:${clientType}.${clientSubtype}.TestVendor and the user is allowed to publish to the vzimp/1/GeoRelevance/${clientType}/${clientSubtype}/TestVendor/j2735_gr/BSM topic then
• a client registered as Vehicle/PassengerCar type will be allowed to publish to the vzimp/1/GeoRelevance/Vehicle/PassengerCar/TestVendor/j2735_gr/BSM, but won't be able to publish to the vzimp/1/GeoRelevance/Software/Application/TestVendor/j2735_gr/BSM topic
• a client registered as Vehicle/Truck will be allowed to publish to the vzimp/1/GeoRelevance/Vehicle/Truck/TestVendor/j2735_gr/BSM topic, but won't be able to publish to the vzimp/1/GeoRelevance/Vehicle/PassengerCar/TestVendor/j2735_gr/BSM topic.
• Subscribe Limit: The maximum number of parallel subscriptions allowed for one application or device to make.
• Publish Rate Limit: The maximum speed that one application or device can publish messages. It is defined in messages per seconds.
• Publish Topics: The list of topics or topic patterns that the applications or devices are allowed to publish messages. The topic patterns can include:
  • variables explained in the Rule Name section above
  • wildcard definition: *, which mean that any content is allowed there just like the + in the MQTT topic
  • OR statements: |, which mean that an enum is listed. For Example: vzimp/1/GeoRelevance/Vehicle/Bus/TestVendor/j2735_gr/BSM|PSM|TIM rule means that the client is allowed to publish to any of the following topics:
    • vzimp/1/GeoRelevance/Vehicle/Bus/TestVendor/j2735_gr/BSM
    • vzimp/1/GeoRelevance/Vehicle/Bus/TestVendor/j2735_gr/PSM
    • vzimp/1/GeoRelevance/Vehicle/Bus/TestVendor/j2735_gr/TIM
  • Exclusions: ^, which means that everything is accepted except the string after the ^ character. For Example: '^MAP' means that anything else can be used in the topics besides 'MAP'. The vzimp/1/GeoRelevance/Vehicle/Bus/TestVendor/j2735_gr/^MAP rule means that the client is not allowed to publish to the vzimp/1/GeoRelevance/Vehicle/Bus/TestVendor/j2735_gr/MAP topic, but it is allowed to publish any other topics:
    • vzimp/1/GeoRelevance/Vehicle/Bus/TestVendor/j2735_gr/BSM
    • vzimp/1/GeoRelevance/Vehicle/Bus/TestVendor/j2735_gr/PSM
    • vzimp/1/GeoRelevance/Vehicle/Bus/TestVendor/j2735_gr/TIM
    • vzimp/1/GeoRelevance/Vehicle/Bus/TestVendor/j2735_gr/SRM
• Subscribe Topics: The list of topics or topic patterns that the applications or devices are allowed to subscribe to. The topic patter has the same rules as the in the publish topics. Please note that most subscription topics will include a wildcard at the end as the publisher's session ID is added to the subscription topics by the ETX message exchange layer. For more detail on the Session ID please refer to the Edge Transportation Exchange user's guide.

In order to use the APIs the user needs to have a ThingSpace account and use their ThingSpace credential to request an Access/Bearer token, which is used to authorize the user, and also request a Session/M2M token to authenticate the user.

• For details on how to obtain the token please refer to the ThingSpace Quick Start Guide - Obtaining an Access Token.
• For detail on how to obtain a Session/M2M token please refer to the ThingSpace Quick Start Guide - Obtaining a VZ-M2M Session Token Programmatically.
• Or watch the ThingSpace API Video Guide 1 and ThingSpace API Video Guide 2 that explains how to obtain both tokens.

Note that the Access Control Configuration Service is designed for the support team as they have to determine which ETX client can access which part of the system. End users will only be able to request the access rules defined for them.

App Config ServiceCopy Anchor Link

The Edge Transportation Exchange's (ETX) Application Configuration APIs allow ETX users to register and manage configurations of the applications in the system.

The configurations are used to define the geofence based messages that are sent to the road users when they enter, leave, reside in, or cross the geofence. Additional trigger conditions based on speed or direction can also be defined. The messages can be of different types, such as Road Side Alert (RSA), Traveler Information Message (TIM), or generic messages. The messages can be public or private, and the system supports the SAE J2735 standard messages, as well as vendor-specific messages.

In order to use the APIs the user needs to have a ThingSpace account and use their ThingSpace credential to request an Access/Bearer token, which is used to authorize the user, and also request a Session/M2M token to authenticate the user.

• For details on how to obtain the token please refer to the ThingSpace Quick Start Guide - Obtaining an Access Token.
• For detail on how to obtain a Session/M2M token please refer to the ThingSpace Quick Start Guide - Obtaining a VZ-M2M Session Token Programmatically.
• Or watch the ThingSpace API Video Guide 1 and ThingSpace API Video Guide 2 that explains how to obtain both tokens.