From a3703114c4e4923f65b32e57706091ea7bb4061f Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Tobi=C3=A1=C5=A1=20Poto=C4=8Dek?= <tobias.potocek@apify.com>
Date: Wed, 14 Feb 2024 13:07:26 +0100
Subject: [PATCH] docs(api): mark run and build endpoints under /acts/:actor_id
 deprecated (#859)

Runs and builds have had dedicated namespaces for a long time
(/actor-runs/:run_id and /actor-builds/:build_id). The API reference
wasn't making it very clear, so this is an attempt to improve the
situation.

Unfortunately, there is no native way for API Blueprint to mark
endpoints as deprecated [1], so good old bold text will have to do
(advice from ChatGPT).

[1] https://github.com/apiaryio/api-blueprint/issues/399
---
 sources/platform/api_v2/api_v2_reference.apib | 20 +++++++++++++++----
 1 file changed, 16 insertions(+), 4 deletions(-)

diff --git a/sources/platform/api_v2/api_v2_reference.apib b/sources/platform/api_v2/api_v2_reference.apib
index d8afbee90..65a98a724 100644
--- a/sources/platform/api_v2/api_v2_reference.apib
+++ b/sources/platform/api_v2/api_v2_reference.apib
@@ -853,8 +853,9 @@ The response is the build object as returned by the
     + Attributes
         - data (Build, required)
 
-## Build object - deprecated [/v2/acts/{actorId}/builds/{buildId}{?token,waitForFinish}]
-API endpoints related to build of the actor were moved under new namespace [actor builds](#reference/actor-builds).
+## Build object [/v2/acts/{actorId}/builds/{buildId}{?token,waitForFinish}]
+
+**[DEPRECATED]** API endpoints related to build of the actor were moved under new namespace [`actor-builds`](#reference/actor-builds).
 
 + Parameters
 
@@ -886,6 +887,8 @@ This endpoint does not require the authentication token. The calls are authentic
 
 ## Abort build [/v2/acts/{actorId}/builds/{buildId}/abort{?token}]
 
+**[DEPRECATED]** API endpoints related to build of the actor were moved under new namespace [`actor-builds`](#reference/actor-builds).
+
 ### Abort build [POST]
 
 Aborts an actor build and returns an object that contains all the details about the build.
@@ -1292,11 +1295,14 @@ To run the actor asynchronously, use the [Run actor](#reference/actors/run-colle
             - type: `run-timeout-exceeded` (string, required)
             - message: `Actor run exceeded timeout of 60 seconds for this API enpoint` (string, required)
 
-## Run object - deprecated [/v2/acts/{actorId}/runs/{runId}{?token,waitForFinish}]
-API endpoints related to run of the actor were moved under new namespace [actor runs](#reference/actor-runs).
+## Run object [/v2/acts/{actorId}/runs/{runId}{?token,waitForFinish}]
+
+**[DEPRECATED]** API endpoints related to run of the actor were moved under new namespace [`actor-runs`](#reference/actor-runs).
 
 ### Get run [GET]
 
+**[DEPRECATED]** API endpoints related to run of the actor were moved under new namespace [`actor-runs`](#reference/actor-runs).
+
 Gets an object that contains all the details about a specific run of an actor.
 
 By passing the optional `waitForFinish` parameter the API endpoint will synchronously wait for the run to finish.
@@ -1319,6 +1325,8 @@ This endpoint does not require the authentication token. The calls are authentic
 
 ## Abort run [/v2/acts/{actorId}/runs/{runId}/abort{?token,gracefully}]
 
+**[DEPRECATED]** API endpoints related to run of the actor were moved under new namespace [`actor-runs`](#reference/actor-runs).
+
 ### Abort run [POST]
 
 Aborts an actor run and returns an object that contains all the details about the run.
@@ -1340,6 +1348,8 @@ Only runs that are starting or running are aborted. For runs with status `FINISH
 
 ## Metamorph run [/v2/acts/{actorId}/runs/{runId}/metamorph{?token,build,targetActorId}]
 
+**[DEPRECATED]** API endpoints related to run of the actor were moved under new namespace [`actor-runs`](#reference/actor-runs).
+
 ### Metamorph run [POST]
 
 Transforms an actor run into a run of another actor with a new input.
@@ -1371,6 +1381,8 @@ For more information, see the [Actor docs](https://docs.apify.com/platform/actor
 
 ## Resurrect run [/v2/acts/{actorId}/runs/{runId}/resurrect{?token,build,timeout,memory}]
 
+**[DEPRECATED]** API endpoints related to run of the actor were moved under new namespace [`actor-runs`](#reference/actor-runs).
+
 ### Resurrect run [POST]
 
 Resurrects a finished actor run and returns an object that contains all the details about the resurrected run.