API: Rename services to integrations

Problem to solve

In #39129 (closed) we decided that we want to rename project services to integrations. This also includes to rename the services endpoint.

There are a few questions we need to answer before we can come up with a solution:

• How can we rename the endpoint without introducing breaking changes?
• How long to we need to wait before we can deprecate the services endpoint?
• How can we document the changes without causing confusion

added Category:Integrations api groupecosystem [DEPRECATED] + 1 deleted label

How long to we need to wait before we can deprecate the services endpoint?

Deprecation of API v3 was announced on February 2017 and we removed it on June 2018. That means we waited about 1,5 years. I think deprecating just one endpoint without switching to a new version is a bad practice so we should wait until we release API v5

I'm putting this in %14.0, in case we decide we want to go through with it. There's currently no plan for a v5 API, so I'm not sure if waiting for that is the right approach, however we can deprecate things in major releases, so that would be acceptable.

Moving this issue again to %14.0 gitlab-com/Product#2337 (closed)

How can we rename the endpoint without introducing breaking changes?

I see a few different options:

• We can keep /services and make it an alias for /integrations. Grape doesn't support aliases but there seems to be a workaround
• We make /services redirect to /integrations. But we can't be sure that all clients implement following redirects.
• We implement integrations in GraphQL and keep /services in REST without renaming. In the documentation we add a note that points to integrations in GraphQL. We can rename the endpoint in v5.

A fourth option, similar to the second point, would be to redirect from /integrations to /services. Old clients could continue to call /services without any changes of behaviour, but all newer clients would need to be able to follow redirects. In a later API version we would make /integrations the canonical route and drop support for /services.

It looks like the params we pass to the endpoints would make sense when the endpoints was alised as /integrations. Only MockCi takes a param called mock_service_url, but that integration is a development-only one, so it probably doesn't matter.

changed the description

mentioned in issue #39129 (closed)

Setting devopsenablement based on ~"group::ecosystem".

added devopssystems + 1 deleted label

added to epic &2504 (closed)

added [deprecated] Accepting merge requests + 1 deleted label

added devopscreate + 1 deleted label and removed devopssystems + 1 deleted label

added sectiondev + 1 deleted label

added priority3 + 1 deleted label

changed milestone to %13.8

changed milestone to %13.12

mentioned in merge request !61210 (merged)

changed milestone to %14.0

set weight to 2

mentioned in issue #201855 (closed)

@tkuah Can I ask for your opinion on this issue? There are some open questions raised and I'm wondering if you have any advice, or can connect us with others who could weigh in.

@.luke

Added #216456 as a blocker issue.

I suspect we may have inadvertently put a too-hard constraint on ourselves by suggesting that API v5 will be also a compatibility layer between GraphQL and REST. We may want to move forward, and just start with a new API v5 that allows us to trim v4 things purely with REST and worry about GraphQL in API v6.

I am becoming convinced of this given the lack of movement with https://docs.gitlab.com/ee/architecture/blueprints/graphql_api/#design-graphql-interoperability-with-rest-api. WDYT @grzesiek @pslaughter

Thanks, @tkuah.

This issue is to support both /services and /integrations endpoints in v4, so perhaps #216456 isn't a blocker?

We have some open questions about how to implement aliasing in REST. @Andysoiron gave some options in #198358 (comment 275258195). I can see that implementing "aliasing" using a redirect from /services -> /integrations could well be a breaking change for some clients. If we were to implement the redirect in the other direction, from /integrations -> /services would that be a better possibility?

Do you have any other ideas or considerations?

I see, if we are implementing both then perhaps the issue description, and title should be updated ?

I don't currently know of good way to do this in Grape. Rails has a very flexible routing DSL which allows this but Grape does not.

Thanks! I see the confusion. I'm used to the GraphQL cycle of changes needing to happen in parallel following a deprecation cycle, but with REST we could just wait and make a breakng change in a future version without supporting both.

marked this issue as related to #216456

mentioned in issue #216456

There is a small number of objects in GraphQL exposed using the name "service".

• An interface called Service.
• Two types BaseService and JiraService.
• Field Project.services, and its connection and edge.
• An enum ServiceType and all of its values.

I think the only way to deprecate a type is really to deprecate the field that exposes that type and make sure no new fields start using it.

So, I think the steps for GraphQL would be:

• Deprecate Project.services, and keep all of those other objects around (the interface, types, and enum) as objects only used by the deprecated field. For good measure we should code comment those objects as being marked for removal with Project.services, so developers don't unknowingly use them in new schema.
• Add Project.integrations and start fresh with new objects.

When the deprecation cycle is up, we delete the deprecated field and all of the old objects.

removed the relation with #216456

mentioned in issue #330670 (closed)

mentioned in merge request !62224 (merged)

added backend + 1 deleted label

@.luke We didn't have the backend label here and I was not aware of this issue.

What do you think is the status of this?

@arturoherrero This issue currently represents work to be done on both the REST API and GraphQL API. It's possible we could covert it into a small Epic.

The initial work for the REST API could be handled with a Rails redirect that aliases integrations to services #198358 (comment 573200607). This would be backend-weight1. We would remove services and make integrations the non-redirecting canonical endpoint in future API v5 #216456.

The GraphQL work would be to copy the existing objects and rename them, deprecating Project.services and code-commenting the old objects to say that they're deprecated #198358 (comment 573215160). This would probably also be backend-weight1 but verging on backend-weight2.

If we keep this as a single issue then think the weight 2 is probably still valid. If we wanted to be more sure, we could make it a weight 3.

I've promoted this into an epic &6186 (closed) and created both issues. Thanks for the suggestion to improve the iteration.

promoted to epic &6186 (closed)

mentioned in epic &6186 (closed)

added 1 deleted label and removed devopscreate label

added devopsmanage label and removed 1 deleted label