Information regarding using PTV JSON API

This forum deals with administrative topics such as monitoring and system setup. It is dedicated to system administrators who do not have to deal with the functions themselves but who have to establish and maintain proper environments.
Public since 15.2.2017

Information regarding using PTV JSON API

Postby biro.daniel » Wed Nov 07, 2018 3:54 pm

Hi All,

We would like to use the PTV JSON APIs instead of the SOAP APIs. With smaller messages we expect to have somewhat increased maximum throughput in some use cases (already using compression). We have also experienced issues under .Net Core with the SOAP adapters, and would like to move away from WCF for maintainability reasons.

Our problem is that we could not find any machine-readable schema in the documentation for the JSON API (as there is a WSDL schema for the SOAP API).
It is not clear what is a valid JSON message for PTV, and how should we generate the correct types for serialization? Is the WSDL intended for this? If so, what tools would you suggest for C#, or for Java?

The best would be an OpenAPI (formerly Swagger) specification conforming schema, as language agnostic clients could be simply generated from that. Do you have such available?

The topics under the Developer’s guide did not answer our questions. Perhaps we have missed it in the documentation. Could you please point us to it?

Thank you very much!

Best Regards,
Daniel
biro.daniel
 
Posts: 35
Joined: Tue Aug 23, 2016 8:08 am

Re: Information regarding using PTV JSON API

Postby Bernd Welter » Thu Nov 08, 2018 6:57 am

Hello Daniel,

forwarded to PM/DEV for a statement about our vision ;-)
From what I've seen so far we have

Serveravailable Interfacesmachine readable Docu
xServer1:*SOAP, JSONWSDL
xServer2:xmap,xlocateSOAP, JSON,RESTWSDL, WADL
xServer2:othersSOAP, JSONWSDL, WADL

WIthin one module JSON and SOAP provide equal access to functionality.

Best regards,
Bernd

PS: ( XSERS-1198 )
Bernd Welter
Manager Technical Consulting & Requirement Engineering
Senior Technical Consultant Developer Components
PTV GROUP - Germany

Bernd at Youtube
User avatar
Bernd Welter
Site Admin
 
Posts: 1220
Joined: Mon Apr 14, 2014 10:28 am

Re: Information regarding using PTV JSON API

Postby ivo.hedtke » Mon Nov 12, 2018 10:18 am

We also work with the JSON Endpoint internally. For that, we started to build the corresponding OpenAPI description ourself. What about the intellectual property of PTV? Would it be possible for us to publish that under a GitHub account? Or is that not allowed?
Dr. Ivo Hedtke
Operations Research Specialist
Global Data Strategy and Analytics
Schenker AG
Kruppstr. 4
45128 Essen
Office B4.OSP.06 (Essen, The Grid)
Phone: +49 1523 757 3622
User avatar
ivo.hedtke
 
Posts: 1
Joined: Mon Nov 12, 2018 9:23 am
Location: Essen, Germany

Re: Information regarding using PTV JSON API

Postby Bernd Welter » Tue Nov 13, 2018 10:55 am

Here's some feedback from DEV (Haba):

Latest info is that we created a prototype for xServer2. During that process we encounterd several obstacles (e.g. missing OpenAPI support for namespaces).The prototype is currently in evaluation at an external resource and we wait for his feedback before we decide about further steps (such as "providing the prototype to selected customers" or "hidden/complete integration into xServer2").
Providing OpenAPI for xServer1 is not part of our roadmap so far.
Please let us know which meta versions you want to use.

From what I see in my personal last communication this is an xServer2 topic.
We would like to know what you've done or want to do in the future so we can compare it with our approaches. Please provide this info to Bernd (also the xServer1 topics).
If you want to provide something on GitHub we are ok with that as long as it is obvious that this is not an official PTV version and that PTV therefore does not provide any support.

Best regards,
Bernd
Bernd Welter
Manager Technical Consulting & Requirement Engineering
Senior Technical Consultant Developer Components
PTV GROUP - Germany

Bernd at Youtube
User avatar
Bernd Welter
Site Admin
 
Posts: 1220
Joined: Mon Apr 14, 2014 10:28 am

Re: Information regarding using PTV JSON API

Postby Bernd Welter » Tue Nov 13, 2018 12:15 pm

By the way:

my colleague R. Immer draw my attention to the following description in the xServer2 docu:
https://xserver2-europe-eu-test.cloud.p ... ciples.htm

Does this help in this context?
Bernd Welter
Manager Technical Consulting & Requirement Engineering
Senior Technical Consultant Developer Components
PTV GROUP - Germany

Bernd at Youtube
User avatar
Bernd Welter
Site Admin
 
Posts: 1220
Joined: Mon Apr 14, 2014 10:28 am

Re: Information regarding using PTV JSON API

Postby biro.daniel » Mon Dec 03, 2018 3:08 pm

Hi!

I understand that OpenAPI might not be a good fit for your API, just brought up as an example we are using, as it is enough for our usecases. (Though I don't understand what kind of namespaces are needed for the API and how OpenAPI does not support them)

We are using xServer1 currently, and as far as I know we are not planning to upgrade to xServer2 yet. We have been using the WCF bindings generated by Visual Studio/disco.exe/wsdl.exe/svcutil.exe for communication with xServer1.
This is working for the moment, however we'd like to try the JSON API for several reasons, including perceived compatibility issues with certain .Net Core versions (latest version seems to solve the regression), larger payload sizes of XML messages, and partly because the low quality of the code generated by these tools, which makes working with the generated API a bit unwieldy.

It is not clear if the types used in the SOAP API are ultimately the same types used in the JSON API. The documentation suggests this. (Also the use of Apache CXF as seen on the classpath seems to suggest this). For example if we would serialize the requests prepared for the SOAP API with a properly set-up JSON serializer, and sent it to the proper endpoint than we would get a response deserializeable to a type generated from the WSDL for the SOAP API?
This was still not clear even from the xServer2 docs, though some hints were pointing in this direction (for example { "$type" : "SomeTypeName" } style type hints for json serializer with type names in the SOAP API in some examples).

If the above mentioned are true than it would still be desireable if the class schemas would still be available in some alternative form for use with the JSON API. It would also be convenient for those using the API from JavaScript.

If OpenAPI is not suitable (I don't see how namespaces come in the picture when working about JSON objects) JSON schema (http://json-schema.org/) of the types used in the xServer1 JSON API would likely be great help already.

As far as we understand the documentation, these POCOs are likely very similiar to the objects used in the SOAP based transfer. However given the code generated by the tooling available we'd rather not manually edit and remove the WCF/SOAP related parts, but would prefer to generate code of the data transfer objects directly, and if needed write the few HTTP GET/POST methods for the delivery.

Best Regards,
Daniel
biro.daniel
 
Posts: 35
Joined: Tue Aug 23, 2016 8:08 am

Re: Information regarding using PTV JSON API

Postby Bernd Welter » Mon Dec 03, 2018 3:21 pm

Hello Daniel,
forwarded to DEV (xsers-1198) ;-)
Best regads,
Bernd
Bernd Welter
Manager Technical Consulting & Requirement Engineering
Senior Technical Consultant Developer Components
PTV GROUP - Germany

Bernd at Youtube
User avatar
Bernd Welter
Site Admin
 
Posts: 1220
Joined: Mon Apr 14, 2014 10:28 am


Return to PTV xServer Administration

cron