feat: add Actor task publication endpoints

[Janjiran]

Part of https://github.com/apify/apify-core/issues/29471

Adding new public endpoint for Actor Task publication API.

---

Blocked by https://github.com/apify/apify-core/pull/29623

[apify-service-account]

✅ Preview for this PR (commit f0609b96) is ready at https://pr-2840.preview.docs.apify.com (see action run).

[apify-service-account]

Important

Action required — @Janjiran please coordinate this docs PR with the Python API client PR linked below.

Because this PR modifies the OpenAPI specification, the generated models in apify-client-python must be regenerated to stay in sync. This has already been done automatically:

A companion PR has been opened in apify-client-python with the regenerated models: apify/apify-client-python#985

• Please make sure to review and merge both PRs together to keep the OpenAPI spec and API clients in sync.
• You can ask for review and help from the Tooling team if needed.

[janbuchar]

This looks legit as far as openapi semantics are considered

[fnesveda]

Is the API final? Why is it so different from the Actor publication API?
For example:

• Actors are published through the "update Actor" endpoint, tasks have special /publish and /unpublish endpoints
• Actors have isPublic, tasks have publishedAt
• Actors have a categories array, tasks have categorization string
• Actors have all the details (seoTitle etc.) on the top level, tasks have it in publicConfig

Can we unify the API so that it's the same as for Actors?

Also, property names like inputSchemaFields, datasetName and datasetView somehow don't capture that they're being used only when showing the task, but they sound like they're relevant to the whole task (e.g. that they limit what input fields can the task process). How about putting them under some displayOptions object?

Also CC @gippy - would you look at this through the lens of the rules for API endpoints you wrote? 🙏

[gippy]

We already discussed this.

The 3 points:

• Actors have isPublic, tasks have publishedAt
• Actors have a categories array, tasks have categorization string
• Actors have all the details (seoTitle etc.) on the top level, tasks have it in publicConfig

Already exist in the current console backend API, so changing them would require migration and complete rewrite.

I already shared my opinion on this when it was going to be impelemented in console backend, but now that train has left the station.

So for API I proposed the option to have the /publish and /unpublish endpoints, because public tasks do not have isPublic field and sending publishedAt: <some date> / publishedAt: null to publish/unpublish is weird. Same sending isPublic field which is just virtual and does not really exist. It matches what the guidelines say and it's not that uncommon.

Since publishing does multiple verification steps, not just for the task detail but also for Actor permission and the Actor "readyness" for task publication it kinda makes sense.

Alternatives are either:

1. Have a single PUT Actor task endpoint which takes a different shape of data and then "transforms" it into real data in the database. Which is hacky
2. Completely redoing the public tasks schema to match Actors, but then the task would have many optional fields which 99% of tasks do not have, which is also is not great.

From my point of view I think it's ok to not have it match, the logic on Actor is not great either with the Actor update endpoint having 9 dependencies and over 400+ lines of code in the updateActor function alone. This way at least the logic is pretty simple. Update task endpoint just checks if the task is valid against schema and all logic related to publication/unpublication is separate. It also makes it much easier to document the errors the endpoints returns.

[fnesveda]

Already exist in the current console backend API, so changing them would require migration and complete rewrite.

I already shared my opinion on this when it was going to be impelemented in console backend, but now that train has left the station.

I really don't agree with this. We can't shape the public API around our internal implementation, we need to make a good public API and then make the implementation work with it.

Writing a migration is a one time pain (and I believe this one can be done through Claude pretty well). A bad API stays with us forever.

So for API I proposed the option to have the /publish and /unpublish endpoints

On their own, these are good, and I agree we should have done the Actors API this way, but that train has surely left the station. So now that we have the Actors API done like this, let's try to have the tasks API consistent with it.

[Janjiran]

Already exist in the current console backend API, so changing them would require migration and complete rewrite.

I already shared my opinion on this when it was going to be impelemented in console backend, but now that train has left the station.

I really don't agree with this. We can't shape the public API around our internal implementation, we need to make a good public API and then make the implementation work with it.

Writing a migration is a one time pain (and I believe this one can be done through Claude pretty well). A bad API stays with us forever.

So for API I proposed the option to have the /publish and /unpublish endpoints

On their own, these are good, and I agree we should have done the Actors API this way, but that train has surely left the station. So now that we have the Actors API done like this, let's try to have the tasks API consistent with it.

Isn't that exactly what we're trying to do here though? To make a good public API and then make the implementation work with it, instead of shaping the new API around the Actor publication design, which you agree is the worse one. So we are designing the tasks API the way we think a good API should look.

I get the consistency point, but if a bad API stays with us forever, then requiring every new API to copy the old pattern is exactly how it stays forever. By following the latest API conventions @gippy put together, the /publish and /unpublish endpoints should be the correct way and later we can add the same endpoints to Actors. That's a non-breaking change and the isPublic flow can be deprecated over time. Copying the Actor design into the tasks API now closes that door.

The schema differences (categories vs. categorization, publicConfig etc) are a fair point but I'd separate it from the publish endpoints discussion.

[fnesveda]

Isn't that exactly what we're trying to do here though? To make a good public API and then make the implementation work with it, instead of shaping the new API around the Actor publication design, which you agree is the worse one. So we are designing the tasks API the way we think a good API should look.

I get your point, and in isolation, the /publish + /unpublish flow is better, but the isPublic flow isn't so bad that it would warrant breaking the consistency across endpoints. This is how I sort the options according to how nice they are:

1. /publish + /unpublish flow on both Actors and tasks
2. isPublic flow on both Actors and tasks
3. /publish + /unpublish on one, isPublic on the other

I get the consistency point, but if a bad API stays with us forever, then requiring every new API to copy the old pattern is exactly how it stays forever. By following the latest API conventions @gippy put together, the /publish and /unpublish endpoints should be the correct way and later we can add the same endpoints to Actors. That's a non-breaking change and the isPublic flow can be deprecated over time. Copying the Actor design into the tasks API now closes that door.

Requiring every new API to copy the old pattern is how we prevent a bad API in the first place - an inconsistent API is a bad API.

If we decide "later we can add the same endpoints to Actors", realistically, we'll never do it, because we'll always have better things to do than changing an ancient, heavily integrated, slightly bad API flow. (I've had my technical purist heart broken many times by the reality of prioritization with limited capacity 🥲)