Fix: Add serviceUri() to ServiceEndpointInterface and clarify endpoint routing docs

- Introduced new method serviceUri(): string to explicitly declare the logical URI segment for each OData endpoint
- Updated ServiceEndpointInterface PHPDoc to reflect modular, config-driven routing
- Clarified semantics of endpoint() and route() to match actual behavior in Endpoint base class
- Aligns terminology with ServiceProvider::boot() logic for endpoint resolution

Author: mgerzabek

src/Endpoint.php

@@ -17,13 +17,19 @@ public function __construct(string $serviceUri)
         $this->serviceUri = trim($serviceUri, '/');
 
         $prefix = rtrim(config('lodata.prefix'), '/');
-        $this->route = ('' === $serviceUri)
+
+        $this->route = ('' === $this->serviceUri)
             ? $prefix
             : $prefix . '/' . $this->serviceUri;
 
         $this->endpoint = url($this->route) . '/';
     }
 
+    public function serviceUri(): string
+    {
+        return $this->serviceUri;
+    }
+
     public function endpoint(): string
     {
         return $this->endpoint;

src/Interfaces/ServiceEndpointInterface.php

@@ -5,33 +5,68 @@
 use Flat3\Lodata\Model;
 
 /**
- * Interface for defining a custom OData service endpoint.
+ * Interface for defining a modular OData service endpoint in Laravel.
  *
- * Implementers can use this interface to expose a specific service under a custom path,
- * define its namespace, route behavior, and optionally provide a statically generated
- * $metadata document.
+ * Implementers of this interface represent individually addressable OData services.
+ * Each mounted under its own URI segment and backed by a schema model.
+ *
+ * This enables clean separation of business domains and supports multi-endpoint
+ * discovery for modular application design.
+ *
+ * Configuration versus Declaration
+ * --------------------------------
+ * The public URI segment used to expose a service is NOT determined by the
+ * implementing class itself, but by the service map in `config/lodata.php`:
+ *
+ * ```php
+ *   'endpoints' => [
+ *       'users' => \App\OData\UsersEndpoint::class,
+ *       'budgets' => \App\OData\BudgetsEndpoint::class,
+ *   ]
+ * ```
+ *
+ * This keeps the routing surface under application control, and avoids
+ * conflicts when two modules declare the same internal segment.
+ *
+ * To implement an endpoint:
+ *   - Extend `Flat3\Lodata\Endpoint` or implement this interface directly
+ *   - Register the class in `config/lodata.php` under a unique segment key
+ *   - Define the `discover()` method to expose entities via OData
  */
 interface ServiceEndpointInterface
 {
+    /**
+     * Returns the ServiceURI segment name for this OData endpoint.
+     *
+     * This value is used in routing and metadata resolution. It Must be globally unique.
+     *
+     * @return string The segment (path identifier) of the endpoint
+     */
+    public function serviceUri(): string;
 
     /**
-     * Returns the relative endpoint identifier within the OData service URI space.
+     * Returns the fully qualified URL for this OData endpoint.
      *
-     * This is the part that appears between the configured Lodata prefix and
-     * the `$metadata` segment, e.g.:
-     *   https://<server>:<port>/<config('lodata.prefix')>/<endpoint>/$metadata
+     *  This includes the application host, port, and the configured segment,
+     *  https://<server>:<port>/<config('lodata.prefix')>/<service-uri>/,
+     *  Example: https://example.com/odata/users/
      *
-     * @return string The relative OData endpoint path
+     * This URL forms the base of the OData service space, and is used for navigation links
+     * and metadata discovery.
+     *
+     * @return string The full URL of the service endpoint
      */
     public function endpoint(): string;
 
     /**
-     * Returns the full request route to this service endpoint.
+     * Returns the internal Laravel route path for this OData service endpoint.
+     *
+     * This is the relative URI path that Laravel uses to match incoming requests,
+     * typically composed of the configured Lodata prefix and the service segment.
      *
-     * This typically resolves to the route path used by Laravel to handle
-     * incoming requests for this specific service instance.
+     * Example: "odata/users"
      *
-     * @return string The full HTTP route to the endpoint
+     * @return string Relative route path for the endpoint
      */
     public function route(): string;
 

src/ServiceProvider.php

@@ -4,6 +4,7 @@
 
 namespace Flat3\Lodata;
 
+use RuntimeException;
 use Composer\InstalledVersions;
 use Flat3\Lodata\Controller\Monitor;
 use Flat3\Lodata\Controller\OData;
@@ -14,6 +15,7 @@
 use Flat3\Lodata\Helper\Flysystem;
 use Flat3\Lodata\Helper\DBAL;
 use Flat3\Lodata\Helper\Symfony;
+use Flat3\Lodata\Interfaces\ServiceEndpointInterface;
 use Illuminate\Foundation\Application;
 use Illuminate\Support\Facades\Route;
 use Symfony\Component\HttpKernel\Kernel;
@@ -64,6 +66,12 @@ public function boot()
                 }
                 else if (array_key_exists($segments[1], $serviceUris)) {
                     $clazz = $serviceUris[$segments[1]];
+                    if (!class_exists($clazz)) {
+                        throw new RuntimeException(sprintf('Endpoint class `%s` does not exist', $clazz));
+                    }
+                    if (!is_subclass_of($clazz, ServiceEndpointInterface::class)) {
+                        throw new RuntimeException(sprintf('Endpoint class `%s` must implement Flat3\\Lodata\\Interfaces\\ServiceEndpointInterface', $clazz));
+                    }
                     $service = new $clazz($segments[1]);
                 }
                 else {