geoserver · aaime · May 27, 2024 · Apr 5, 2024 · Apr 8, 2024 · Apr 8, 2024
diff --git a/doc/en/api/1.0.0/urlchecks.yaml b/doc/en/api/1.0.0/urlchecks.yaml
@@ -0,0 +1,239 @@
+---
+swagger: '2.0'
+info:
+  version: 1.0.0
+  title: GeoServer UrlCheck
+  description: An URL External Access Check is the check performed on user provided URLs that GeoServer will use to access remote resources.
+  contact:
+    name: GeoServer
+    email: 'geoserver-users@sourceforge.net'
+    url: 'http://geoserver.org/comm/'
+host: localhost:8080
+basePath: /geoserver/rest
+
+paths:
+  /urlchecks:
+    get:
+      operationId: getUrlChecks
+      tags:
+        - "UrlChecks"
+      summary: Get a list of URL checks
+      description: Displays a list of all URL checks on the server. Use the "Accept:" header to specify format or append an extension to the endpoint (example "/urlchecks.xml" for XML)
+      produces:
+        - text/html
+        - application/json
+        - application/xml
+      responses:
+        200:
+          description: OK
+          schema:
+            $ref: "#/definitions/urlChecks"
+          examples:
+            text/html: |
+              <html>
+                <head>
+                    <title>GeoServer Configuration</title>
+                    <meta name="ROBOTS" content="NOINDEX, NOFOLLOW" />
+                </head>
+                <body>
+                    <ul>
+                        <li><a href="http://localhost:8080/geoserver/rest/urlchecks/external.html">external</a></li>
+                        <li><a href="http://localhost:8080/geoserver/rest/urlchecks/icons.html">icons</a></li>
+                        <li><a href="http://localhost:8080/geoserver/rest/urlchecks/safeWFS.html">safeWFS</a></li>
+                    </ul>
+                </body>
+              </html>
+            application/xml: |
+              <urlChecks>
+                <urlCheck>
+                    <name>external</name>
+                    <atom:link xmlns:atom="http://www.w3.org/2005/Atom" rel="alternate" href="http://localhost:8080/geoserver/rest/urlchecks/external.xml" type="application/atom+xml"/>
+                </urlCheck>
+                <urlCheck>
+                    <name>icons</name>
+                    <atom:link xmlns:atom="http://www.w3.org/2005/Atom" rel="alternate" href="http://localhost:8080/geoserver/rest/urlchecks/icons.xml" type="application/atom+xml"/>
+                </urlCheck>
+                <urlCheck>
+                    <name>safeWFS</name>
+                    <atom:link xmlns:atom="http://www.w3.org/2005/Atom" rel="alternate" href="http://localhost:8080/geoserver/rest/urlchecks/safeWFS.xml" type="application/atom+xml"/>
+                </urlCheck>
+              </urlChecks>
+            application/json: |
+              {"urlchecks":{"urlcheck":[
+                      {"name":"external","href":"http:\/\/localhost:8080\/geoserver\/rest\/urlchecks\/external.json"},
+                      {"name":"icons","href":"http:\/\/localhost:8080\/geoserver\/rest\/urlchecks\/icons.json"},
+                      {"name":"safeWFS","href":"http:\/\/localhost:8080\/geoserver\/rest\/urlchecks\/safeWFS.json"}]}}
+        401:
+          description: Unauthorized
+
+    post:
+      operationId: postUrlChecks
+      tags:
+        - "UrlChecks"
+      summary: add a new URL check to GeoServer
+      description: Adds a new URL check to the server
+      parameters:
+        - name: urlcheckBody
+          description: The url check body to upload.
+          in: body
+          required: true
+          schema:
+            $ref: "#/definitions/urlCheck"
+      consumes:
+        - application/json
+        - application/xml
+      produces:
+        - text/html
+        - application/json
+        - application/xml
+      responses:
+        201:
+          description: Created
+          schema:
+            type: string
+          headers:
+            Location:
+              description: URL where the newly created URL check can be found
+              type: string
+        400:
+          description: Unable to add provided URL check as it misses required fields
+        409:
+          description: Unable to add URL check as it already exists
+
+    put:
+      operationId: putUrlChecks
+      tags:
+        - "UrlChecks"
+      responses:
+        405:
+          description: Not permitted
+
+    delete:
+      operationId: deleteUrlChecks
+      tags:
+        - "UrlChecks"
+      responses:
+        405:
+          description: Not permitted
+
+  /urlchecks/{urlcheckname}:
+    get:
+      operationId: getUrlCheck
+      tags:
+        - "UrlChecks"
+      summary: Retrieve a URL check
+      description: Retrieves a single URL check definition. Use the "Accept:" header to specify format or
+        append an extension to the endpoint (example "/urlchecks/{urlcheck}.xml" for XML).
+      produces:
+        - application/xml
+        - application/json
+        - text/html
+      parameters:
+        - name: urlcheckname
+          description: the name of the URL check to fetch.
+          in: path
+          required: true
+          type: string
+      responses:
+        200:
+          description: OK
+          schema:
+            $ref: "#/definitions/urlCheck"
+          examples:
+            application/xml: |
+              <urlChecks>
+                  <urlCheck>
+                      <name>icons</name>
+                      <atom:link xmlns:atom="http://www.w3.org/2005/Atom" rel="alternate" href="http://localhost:8080/geoserver/rest/urlchecks/icons.xml" type="application/atom+xml"/>
+                  </urlCheck>
+              </urlChecks>
+
+            application/json: |
+              {
+                "urlCheck": {
+                    "name": "icons",
+                    "description": "External graphic icons",
+                    "enabled": true,
+                    "regex": "^https://styles.server.net/icons/.*$"
+                }
+              }
+        404:
+          description: URL check does not exist
+
+    post:
+      operationId: postUrlCheck
+      tags:
+        - "UrlChecks"
+      responses:
+        405:
+          description: Not permitted
+
+    put:
+      summary: Update a URL check
+      tags:
+        - "UrlChecks"
+      description: Changes the URL check with the provided data.
+      operationId: putUrlCheck
+      consumes:
+        - application/json
+        - application/xml
+      responses:
+        200:
+          description: Modified
+        400:
+          description: Cannot perform the change to the URL check as required fields are missing
+        404:
+          description: Url check not found
+      parameters:
+        - name: urlcheckname
+          in: path
+          description: name of URL check.
+          required: true
+          type: string
+        - name: workspaceBody
+          description: The url check body to perform the change against.
+          in: body
+          required: true
+          schema:
+            $ref: "#/definitions/urlCheck"
+
+    delete:
+      operationId: deleteUrlCheck
+      tags:
+        - "UrlChecks"
+      parameters:
+        - name: urlcheckname
+          in: path
+          description: name of URL check to delete.
+          required: true
+          type: string
+      responses:
+        200:
+          description: Successfully deleted URL check
+        404:
+          description: Url check doesn't exist
+
+definitions:
+  urlCheck:
+    type: object
+    required:
+      - name
+      - regex
+    properties:
+      name:
+        type: string
+        description: name of the URL check
+      description:
+        type: string
+        description: description for the URL check
+      enabled:
+        type: boolean
+        description: enabled status of the URL check
+        default: true
+      regex:
+        type: string
+        description: regex to perform the check with
+  urlChecks:
+    type: array
+    items:
+      $ref: "#/definitions/urlCheck"
diff --git a/doc/en/pom.xml b/doc/en/pom.xml
@@ -598,6 +598,18 @@
               <language/>
             </configuration>
           </execution>
+          <execution>
+            <id>urlchecks</id>
+            <phase>process-resources</phase>
+            <goals>
+              <goal>generate</goal>
+            </goals>
+            <configuration>
+              <inputSpec>${project.basedir}/api/1.0.0/urlchecks.yaml</inputSpec>
+              <output>${project.build.directory}/api/urlchecks</output>
+              <language/>
+            </configuration>
+          </execution>
         </executions>
       </plugin>
 

diff --git a/doc/en/user/source/rest/api/index.rst b/doc/en/user/source/rest/api/index.rst
@@ -34,3 +34,4 @@ This section describes the GeoServer REST configuration API.
    accesscontrol
    userrole
    resources
+   urlchecks
diff --git a/doc/en/user/source/rest/api/urlchecks.rst b/doc/en/user/source/rest/api/urlchecks.rst
@@ -0,0 +1,94 @@
+.. _rest_api_urlchecks:
+
+URL Checks
+==========
+
+An ``URL External Access Check`` is the check performed on user provided URLs that GeoServer will use to access remote resources.
+
+``/urlchecks[.<format>]``
+--------------------------
+
+Returns all url checks.
+
+.. list-table::
+   :header-rows: 1
+
+   * - Method
+     - Action
+     - Status code
+     - Formats
+     - Default Format
+   * - GET
+     - List all url checks
+     - 200
+     - HTML, XML, JSON
+     - JSON
+   * - POST
+     - Create a new url check
+     - 201 with ``Location`` header
+     - XML, JSON
+     -
+   * - PUT
+     -
+     - 405
+     -
+     -
+   * - DELETE
+     -
+     - 405
+     -
+     -
+
+``/urlchecks/<uc>[.<format>]``
+-------------------------------
+
+Returns a specific url check.
+
+.. list-table::
+   :header-rows: 1
+
+   * - Method
+     - Action
+     - Status code
+     - Formats
+     - Default Format
+     - Parameters
+   * - GET
+     - Return url check ``uc``
+     - 200
+     - HTML, XML, JSON
+     - JSON
+     -
+   * - POST
+     -
+     - 405
+     -
+     -
+     -
+   * - PUT
+     - 200
+     - Modify url check ``uc``
+     - XML, JSON
+     -
+     -
+   * - DELETE
+     - 200
+     - Delete url check ``uc``
+     - XML, JSON
+     -
+     -
+
+Exceptions
+~~~~~~~~~~
+
+.. list-table::
+   :header-rows: 1
+
+   * - Exception
+     - Status code
+   * - POST or PUT for a url check missing required fields
+     - 401
+   * - GET or DELETE for a url check that does not exist
+     - 404
+   * - POST for a url check that already exists
+     - 409
diff --git a/doc/en/user/source/rest/index.rst b/doc/en/user/source/rest/index.rst
@@ -43,6 +43,7 @@ The following links provide direct access to the GeoServer REST API documentatio
 * :api:`/wmtslayers <wmtslayers.yaml>`
 * :api:`/wmtsstores <wmtsstores.yaml>`
 * :api:`/workspaces <workspaces.yaml>`
+* :api:`/urlchecks <urlchecks.yaml>`
 * :api:`/usergroup <usergroup.yaml>`
 * :api:`/roles <roles.yaml>`
 
@@ -97,7 +98,8 @@ This section contains a number of examples which illustrate some of the most com
    stores   
    imagemosaic
    appschema
-
+   urlchecks
+
 
 
 .. toctree::