Questions about the REST API and plcnext.help

John

Hi there,

New PLCNext user here! Excited to work with your devices. I've got three questions:

1. I saw the plcnext.help docs mentioned a version number for the REST API.

It provides the version of the service in the form of v{Major}.{Minor}. The api path can be used to retrieve the latest version of the service. The current version path is v1.1.

On my device - a fresh install - the API version is 1.4.*. Should the docs be updated?

2. Is there a way (next to this forum) to suggest edits to the docs? I.e. if you would host the docs on Github, I could open a PR?

3. Are there public change logs somewhere of the REST API versioning? Or is there a place where I can subscribe to change logs updates? And are REST API versions always connected to new firmware updates? Or are there other ways API changes could occur without us knowing?

Kind regards,

John

Frank Phoenix Contact Deutschland Support

Hi kemon,

I've moved the post to our PLCnext Technology Section.

Well, you have raised a few interesting and important points and I guess it will need a bit time to answer them.

First of all it is important to know that we've started the story of the REST interface for our own usage with the PLCnext HMI and the corresponding clients.

As it makes sense we've decided to make the Data Access interface public available and to document the related calls.
They did not change until version 1.1, but you're defenetly right that we should at least mention the fact that a newer version is currently implemented.

The major changes in those newer versions are related to some new features (like charting for the real-time datalogger), which needs a bit more time to document them also for the public.

I also like your idea of move the documentation of the REST interface to our PLCnext Technology · GitHub channel.
Well, I can not promise the world, but I'll talk with the dev and the product manager if this would be possible...

cu,

Frank

John

Hi Frank,

Thanks for the quick response!  

Regarding the change log for the REST interface, I come from a 'web' context in which API's can quickly change versions (sometimes even from week-to-week), especially if a product is still developing. Now I don't assume that'll be the case for the PLCNext because updates to the API seem to be paired with firmware updates (which are released every 3 months), but it's nice to get an overview of changes developers can browse through to see if any breaking changes are made (or to discover new functionalities in a new release!). An example of a well maintained change log is Bootstrap: https://github.com/twbs/bootstrap/releases. I'm not sure whether such a public change log fits your ambition - but you could also include it in a newsletter to clients as  PDF when you release a new firmware version.

I'll wait until you have some more information regaring the documentation, and keep the topic open for now.

Thanks!

John

Frank Phoenix Contact Deutschland Support

Hi John,

well, at least we are not going to plan breaking chances within weeks ;-)

As you sad is the api bound to the firmware and can be called by its version.
In that way we can assure that also older PLCnext Engineer HMI versions are still compatible with newer firmware versions.

I've had a few chatts in the last days with the dev team of the api and they have said that at least in the data access module were no changes from 1.1 to 1.4.

Now, also based on your request, we are planning to update the infocenter, but this could take a little while as there are many other points on the list...

I still like the GitHub idea, and that defenetly that a changelog is needed.

Take care,

Frank