Forsøk på opprydning i appPath vs basePath (#1783)

* Remove most use of `{appPath}` as it is not defined `{basePath}` is somewhat defined at the start, but `{appPath}` just sort of shows up suddenly. The other alternative is to define `{appPath}` along with `{basePath}` better, and use `{appPath}` more consistantly, but I'm not sure which one is best. * Replace last two `{appPath}` and add missing `/meta` To get the process, you need to include `/meta` in the URL, so ensure its mentioned in the docs, and also use `{basePath}` to ensure we know what we are talking about * Explicitly name `{basePath}` on the index pages This is an attempt to remove confusion while browsing, and hopefully get hits if you search. * chore: remove dangling whitespace --------- Co-authored-by: Terje Holene <[email protected]>
Altinn · Sep 12, 2024 · 4e30d15 · 4e30d15
1 parent bbebd2f
commit 4e30d15
Show file tree

Hide file tree

Showing 8 changed files with 27 additions and 27 deletions.
diff --git a/content/api/apps/_index.en.md b/content/api/apps/_index.en.md
@@ -12,7 +12,7 @@ aliases:
 
 The features documented here are the default features of any app created based on the app template in Altinn Studio. Application owners are free to make changes to this, but it is probably safe to say that removal of features will be extremely rare. Any app with changes to its API should have its own documentation published by the application owner.
 
-All app API endpoints have the same URL base path that will vary based on application owner and application name.
+All app API endpoints have the same URL base path that will vary based on application owner and application name. This is called `{basePath}` throughout the documentation.
 
 **Test environment (TT02)**
 ```http
@@ -24,6 +24,6 @@ https://{org}.apps.tt02.altinn.no/{org}/{appname}
 https://{org}.apps.altinn.no/{org}/{appname}
 ```
 
-The URL identifies the application owner specific hostname using the short name (**org**), and the identifier of the app consisting of both the application owner short name and the name of the app (**org/appname**). 
+The URL identifies the application owner specific hostname using the short name (**org**), and the identifier of the app consisting of both the application owner short name and the name of the app (**org/appname**).
 
 {{<children />}}
diff --git a/content/api/apps/_index.nb.md b/content/api/apps/_index.nb.md
@@ -10,7 +10,7 @@ tags: [api]
 
 De API-funksjonene som er dokumentert her er standardfunksjoner i en app basert på app-malen i Altinn Studio. Applikasjonseiere kan fritt gjøre endringer, men det er relativt trygt å anta at fjerning av funksjoner vil være ekstremt sjeldent. Enhver app med tillegg eller endringer skal ha sin egen dokumentasjon publisert av applikasjonseieren.
 
-Alle app-API-adresser starter med samme navn og filsti, men de varierer fra én app til en annen basert på appeier og appnavn.
+Alle app-API-adresser starter med samme navn og filsti, men de varierer fra én app til en annen basert på appeier og appnavn. Dette er kalt `{basePath}` i dokumentasjonen.
 
 **Testmiljø (TT02)**
 ```http

diff --git a/content/api/apps/data-elements/_index.en.md b/content/api/apps/data-elements/_index.en.md
@@ -123,7 +123,7 @@ The endpoint returns the data element metadata document that was created.
     "contentType": "application/xml",
     "blobStoragePath": "org/app/762011d1-d341-4c0a-8641-d8a104e83d30/data/692ee7df-82a9-4bba-b2f2-c8c4dac69aff",
     "selfLinks": {
-        "apps": "{appPath}/instances/347829/762011d1-d341-4c0a-8641-d8a104e83d30/data/692ee7df-82a9-4bba-b2f2-c8c4dac69aff",
+        "apps": "{basePath}/api/v1/instances/347829/762011d1-d341-4c0a-8641-d8a104e83d30/data/692ee7df-82a9-4bba-b2f2-c8c4dac69aff",
         "platform": "{storagePath}/instances/347829/762011d1-d341-4c0a-8641-d8a104e83d30/data/692ee7df-82a9-4bba-b2f2-c8c4dac69aff"
     },
     "filename": "default.xml",
@@ -154,4 +154,4 @@ Endpoint for deleting an existing data element. It is currently not possible to
 DELETE basePath/{dataGuid}
 ```
 
-{{<children />}}
+{{<children />}}
diff --git a/content/api/apps/data-elements/_index.nb.md b/content/api/apps/data-elements/_index.nb.md
@@ -121,7 +121,7 @@ The endpoint returns the data element metadata document that was created.
     "contentType": "application/xml",
     "blobStoragePath": "org/app/762011d1-d341-4c0a-8641-d8a104e83d30/data/692ee7df-82a9-4bba-b2f2-c8c4dac69aff",
     "selfLinks": {
-        "apps": "{appPath}/instances/347829/762011d1-d341-4c0a-8641-d8a104e83d30/data/692ee7df-82a9-4bba-b2f2-c8c4dac69aff",
+        "apps": "{basePath}/api/v1/instances/347829/762011d1-d341-4c0a-8641-d8a104e83d30/data/692ee7df-82a9-4bba-b2f2-c8c4dac69aff",
         "platform": "{storagePath}/instances/347829/762011d1-d341-4c0a-8641-d8a104e83d30/data/692ee7df-82a9-4bba-b2f2-c8c4dac69aff"
     },
     "filename": "default.xml",
@@ -152,4 +152,4 @@ Endpoint for deleting an existing data element. It is currently not possible to
 DELETE basePath/{dataGuid}
 ```
 
-{{<children />}}
+{{<children />}}
diff --git a/content/api/apps/process/_index.en.md b/content/api/apps/process/_index.en.md
@@ -23,7 +23,7 @@ A process is represented by an process model in BPMN/XML notation. Each task has
 Get the application's process model.
 
 ```http
-GET {appPath}/process
+GET {basePath}/api/v1/meta/process
 ```
 
 Returns the bpmn file defining the process.
@@ -62,7 +62,7 @@ which signify the behaviour of the task. So far we have defined the following:
 ## Get process state of a specific instance
 
 ```http
-GET {appPath}/instances/347829/41e57962-dfb7-4502-a4dd-8da28b0885fc/process
+GET {basePath}/api/v1/instances/347829/41e57962-dfb7-4502-a4dd-8da28b0885fc/process
 ```
 
 For an ongoing process this process state can look like the json below. It indicates that the process was started at a given date time and that it's current task is *Task_1*.
@@ -183,7 +183,7 @@ The system will generate a number of process related events, which can be found
 Based on the process events the history of the instance's process is generated. The following illustrates an ended process:
 
 ```http
-GET {appPath}/instances/347829/41e57962-dfb7-4502-a4dd-8da28b0885fc/process/history
+GET {basePath}/api/v1/instances/347829/41e57962-dfb7-4502-a4dd-8da28b0885fc/process/history
 ```
 
 ```json
@@ -214,7 +214,7 @@ GET {appPath}/instances/347829/41e57962-dfb7-4502-a4dd-8da28b0885fc/process/hist
 To start a process one can post start to the process endpoint.
 
 ```http
-POST {appPath}/instances/347829/41e57962-dfb7-4502-a4dd-8da28b0885fc/process/start[?startEvent=StartEvent_1]
+POST {basePath}/api/v1/instances/347829/41e57962-dfb7-4502-a4dd-8da28b0885fc/process/start[?startEvent=StartEvent_1]
 ```
 
 This will start the process and move the process state to the first task from the given start. If process has more than one start event, then the client has to chose which one to start with the startEvent query parameter.
@@ -226,7 +226,7 @@ The process logic attempts to finish the current task and then moves the process
 ![Flowchart for completing a task](process-completeTask.png "Process next task")
 
 ```http
-PUT {appPath}/instances/347829/41e57962-dfb7-4502-a4dd-8da28b0885fc/process/next[?id=Task_2]
+PUT {basePath}/api/v1/instances/347829/41e57962-dfb7-4502-a4dd-8da28b0885fc/process/next[?id=Task_2]
 ```
 
 ## Complete the process
@@ -238,7 +238,7 @@ If a task's exit condition is not met, the process will be stopped in the last v
 ![Flowchart for completing a process](process-completeProcess.png "Complete the process")
 
 ```http
-PUT {appPath}/instances/347829/41e57962-dfb7-4502-a4dd-8da28b0885fc/process/completeProcess
+PUT {basePath}/api/v1/instances/347829/41e57962-dfb7-4502-a4dd-8da28b0885fc/process/completeProcess
 ```
 
 
@@ -247,13 +247,13 @@ PUT {appPath}/instances/347829/41e57962-dfb7-4502-a4dd-8da28b0885fc/process/comp
 Returns an list of the next tasks/events that can be reached from the current task.
 
 ```http
-GET {appPath}/instances/347829/41e57962-dfb7-4502-a4dd-8da28b0885fc/process/next
+GET {basePath}/api/v1/instances/347829/41e57962-dfb7-4502-a4dd-8da28b0885fc/process/next
 ```
 
 ## Start a task
 
 If you are at a specific task and want to start the next task you can try to put next to the process endpoint. The process controller then tries to close the current task and start the wanted task. Updates process state accordingly. If exit condition of current task is not met, an error will be returned. If the task is not directly reachable by the flow, an error will be returned.
 
 ```http
-PUT {appPath}/instances/347829/41e57962-dfb7-4502-a4dd-8da28b0885fc/process/next?id=Task_2
+PUT {basePath}/api/v1/instances/347829/41e57962-dfb7-4502-a4dd-8da28b0885fc/process/next?id=Task_2
 ```
diff --git a/content/api/apps/process/_index.nb.md b/content/api/apps/process/_index.nb.md
@@ -21,7 +21,7 @@ A process is represented by an process model in BPMN/XML notation. Each task has
 Get the application's process model.
 
 ```http
-GET {appPath}/process
+GET {basePath}/api/v1/meta/process
 ```
 
 Returns the bpmn file defining the process.
@@ -60,7 +60,7 @@ which signify the behavior of the task. So far we have defined the following:
 ## Get process state of a specific instance
 
 ```http
-GET {appPath}/instances/347829/41e57962-dfb7-4502-a4dd-8da28b0885fc/process
+GET {basePath}/api/v1/instances/347829/41e57962-dfb7-4502-a4dd-8da28b0885fc/process
 ```
 
 For an ongoing process this process state can look like the json below. It indicates that the process was started at a given date time and that it's current task is *Task_1*.
@@ -181,7 +181,7 @@ The system will generate a number of process related events, which can be found
 Based on the process events the history of the instance's process is generated. The following illustrates an ended process:
 
 ```http
-GET {appPath}/instances/347829/41e57962-dfb7-4502-a4dd-8da28b0885fc/process/history
+GET {basePath}/api/v1/instances/347829/41e57962-dfb7-4502-a4dd-8da28b0885fc/process/history
 ```
 
 ```json
@@ -212,7 +212,7 @@ GET {appPath}/instances/347829/41e57962-dfb7-4502-a4dd-8da28b0885fc/process/hist
 To start a process one can post start to the process endpoint.
 
 ```http
-POST {appPath}/instances/347829/41e57962-dfb7-4502-a4dd-8da28b0885fc/process/start[?startEvent=StartEvent_1]
+POST {basePath}/api/v1/instances/347829/41e57962-dfb7-4502-a4dd-8da28b0885fc/process/start[?startEvent=StartEvent_1]
 ```
 
 This will start the process and move the process state to the first task from the given start. If process has more than one start event, then the client has to chose which one to start with the startEvent query parameter.
@@ -224,7 +224,7 @@ The process logic attempts to finish the current task and then moves the process
 ![Flowchart for completing a task](process-completeTask.png "Process next task")
 
 ```http
-PUT {appPath}/instances/347829/41e57962-dfb7-4502-a4dd-8da28b0885fc/process/next[?id=Task_2]
+PUT {basePath}/api/v1/instances/347829/41e57962-dfb7-4502-a4dd-8da28b0885fc/process/next[?id=Task_2]
 ```
 
 ## Complete the process
@@ -236,7 +236,7 @@ If a task's exit condition is not met, the process will be stopped in the last v
 ![Flowchart for completing a process](process-completeProcess.png "Complete the process")
 
 ```http
-PUT {appPath}/instances/347829/41e57962-dfb7-4502-a4dd-8da28b0885fc/process/completeProcess
+PUT {basePath}/api/v1/instances/347829/41e57962-dfb7-4502-a4dd-8da28b0885fc/process/completeProcess
 ```
 
 
@@ -245,13 +245,13 @@ PUT {appPath}/instances/347829/41e57962-dfb7-4502-a4dd-8da28b0885fc/process/comp
 Returns an list of the next tasks/events that can be reached from the current task.
 
 ```http
-GET {appPath}/instances/347829/41e57962-dfb7-4502-a4dd-8da28b0885fc/process/next
+GET {basePath}/api/v1/instances/347829/41e57962-dfb7-4502-a4dd-8da28b0885fc/process/next
 ```
 
 ## Start a task
 
 If you are at a specific task and want to start the next task you can try to put next to the process endpoint. The process controller then tries to close the current task and start the wanted task. Updates process state accordingly. If exit condition of current task is not met, an error will be returned. If the task is not directly reachable by the flow, an error will be returned.
 
 ```http
-PUT {appPath}/instances/347829/41e57962-dfb7-4502-a4dd-8da28b0885fc/process/next?id=Task_2
+PUT {basePath}/api/v1/instances/347829/41e57962-dfb7-4502-a4dd-8da28b0885fc/process/next?id=Task_2
 ```
diff --git a/content/api/apps/validation/_index.en.md b/content/api/apps/validation/_index.en.md
@@ -77,5 +77,5 @@ The validate method takes a data file of an dataType and performs validation on
 ![Flowchart for data validation](data-validate.png "Validate data")
 
 ```http
-PUT {appPath}/validate?dataType=modelA
-```
+PUT {basePath}/api/v1/validate?dataType=modelA
+```
diff --git a/content/api/apps/validation/_index.nb.md b/content/api/apps/validation/_index.nb.md
@@ -75,5 +75,5 @@ The validate method takes a data file of an dataType and performs validation on
 ![Flowchart for data validation](data-validate.png "Validate data")
 
 ```http
-PUT {appPath}/validate?dataType=modelA
-```
+PUT {basePath}/api/v1/validate?dataType=modelA
+```