Feature review pre-migration of Drupal functionality

changed the description

https://api-staging.eclipse.org/mailing_lists/

On production, the endpoint looks like this /foundation/mailing-list. Is it intentional that we are changing the url?

The following elements doesn't match production.

"is_private": false,
"is_for_news_archives": false,
"is_disabled": false,
"is_deleted": false,
"is_subscribable": true

On production the values are either "1" or "0".

Also noticing the create_date value looks like this: "create_date": "0005-01-13T10:01:59Z". Not sure if that's an issue but that's a weird looking date. On production the dates are formatted like this: 2019-12-02 11:36:47.

https://api-staging.eclipse.org/mailing_lists/gendoc-dev

The JSON is a bit different from prod.

Was that intended? If so, we might have to update or code that does retrieves.

https://api-staging.eclipse.org/mailing_lists/projects

The projects endpoint is empty on production so I can't compare but the data is the same as for the other endpoints on staging.

mentioned in merge request !10 (merged)

mentioned in commit 24aa0add

As a general reference, this is something @cguindon and I worked on when I first started, but forgot to disseminate...whoops! Its a set of API guidelines for our APIs. I'm fixing some of our APIs now, and going to make plans to introduce the breaking changes needed so that they can be performed at some time in the future.

https://gitlab.eclipse.org/eclipsefdn/it/webdev/eclipsefdn-webdev-toolkit/-/wikis/Documentation/Processes/API-Guidelines

These guidelines explain at least part of the change, in that resources should be plural. I've fixed the underscore to be a hyphen, so that should be live soon. Otherwise, we bound to this endpoint to avoid collision with the current endpoint.

On production the values are either "1" or "0".

This is just a binary representation of booleans, so it should be directly castable if it's not usable as is. IMO, we shouldn't misrepresent data types in Java because Drupal uses smallint for booleans for whatever reason.

Also noticing the create_date value looks like this: "create_date": "0005-01-13T10:01:59Z". Not sure if that's an issue but that's a weird-looking date. On production, the dates are formatted like this: 2019-12-02 11:36:47.

The format is very intentional, as we are moving to a date standard (RFC 3339, which is a sub-spec of ISO 8601) to standardize formats to something universal. The 0002 bit is weird though...I'll have to try and pull that value out to see why it's doing that.

The JSON is a bit different from prod.

The difference seems to be fields that were previously omitted from the database rather than new data. This data set is based on the same information used in Drupal so this data is all available to you, even if it isn't used. Does drupal fail on unknown fields in serialization? I know that our Java APIs at least skip unknown fields by default, and figured it was probably standard practice.

The part That I find is different from the retrieve is that on production we have an array of items as for staging you are only returning one item. Not saying it's wrong but, if we're expecting an array of items and we only get one, code is going to break on the other end.

staging Example: {...}

Prod Example: [{...}]

@epoirier Do you know if other services like some of our websites are using this API?

I recall that we needed to build this for the crossminer project but I am wondering if we are using this for other things.

That's a good question.

I know we are not using it to populate the mailing list pages on accounts but other then that, I don't know who might be using it.

This is just a binary representation of booleans, so it should be directly castable if it's not usable as is. IMO, we shouldn't misrepresent data types in Java because Drupal uses small int for booleans for whatever reason.

+1 I prefer we use bool for this rather than a string for 0,1.

The format is very intentional, as we are moving to a date standard (RFC 3339, which is a sub-spec of ISO 8601) to standardize formats to something universal. The 0002 bit is weird though...I'll have to try and pull that value out to see why it's doing that.

+1

However, we are breaking API. If we don't have any internal service using this, we simply inform crossminer of the change and see if they have any concerns. I don't think so but it should be fairly easy to confirm since Boris is now an employee of the foundation.

Sounds good with me!

@bbaldassari2kd we are looking to migrate the mailing-list endpoint to Java with some slight, though still breaking, changes to the format to modernize in some places. These changes aren't large in scope, but we want to try and make this process as smooth as possible! See the above conversations for more details, but the biggest changes are as follows:

date format to include a timestamp (consistency with other APIs)
Retrieval of specific assets are no longer wrapped in arrays. Getting a specific mailing list like with https://api-staging.eclipse.org/mailing_lists/gendoc-dev will return an object at the root rather than an array.
Booleans are now actual booleans instead of stringified 0s and 1s.

Please let us know if you have any concerns with this!

Hi @malowe,

Thanks, note taken. Have a beautiful Saturday!

mentioned in commit 6f524c8e

@malowe is there anything else to review here?

Can we close this issue?

Thanks.

closed

Feature review pre-migration of Drupal functionality

Designs

Child items ...

Activity