Add data source doc

docs/concepts/data-source.md

@@ -0,0 +1,59 @@
+# Data source
+
+A data source defines basic reusable properties of an API and is required to define a [query](query.md).
+
+## DatasourceInterface
+
+At its simplest, a data source implements `DatasourceInterface` and describes itself with the following methods:
+
+- `get_display_name(): string`: Return the display name of the data source.
+- `get_image_url(): string|null`: Optionally, return an image URL that can represent the data source in UI.
+
+## HttpDatasource
+
+`HttpDatasource` implements `DatasourceInterface` and provides additional common reusable properties of an HTTP API:
+
+- `get_endpoint(): string`: Returns the base URL of the API endpoint. This can be overridden by a query.
+- `get_request_headers(): array`: Returns an associative array of HTTP headers to be sent with each request. This is a common place to set authentication headers such as `Authorization`. This array can be extended or overridden by a query.
+
+## Example
+
+Most HTTP-powered APIs can be represented by extending `HttpDatasource`. Here's an example of a data source for US ZIP code data:
+
+```php
+class ZipCodeDatasource extends HttpDatasource {
+	public function get_display_name(): string {
+		return 'US ZIP codes';
+	}
+
+	public function get_endpoint(): string {
+		return 'https://api.zippopotam.us/us/';
+	}
+
+	public function get_request_headers(): array {
+		return [
+			'Content-Type' => 'application/json',
+		];
+	}
+}
+```
+
+## Custom data source
+
+APIs that do not use HTTP as transport may require a custom data source. Implement `DatasourceInterface` and provide additional methods that define reusable properties of your API. The actual implementation of your transport will likely be provided extending `QueryRunner`.
+
+```php
+class WebDavDatasource implements DatasourceInterface {
+	public function get_display_name(): string {
+		return 'WebDAV Files';
+	}
+
+    public function get_image_url(): null {
+        return null;
+    }
+
+	public function get_webdav_root(): string {
+		return 'webdavs://webdav.example.com/';
+	}
+}
+```

inc/Config/Datasource/CompatibleHttpDatasource.php → inc/Config/Datasource/CodedHttpDatasource.php

@@ -3,14 +3,15 @@
 namespace RemoteDataBlocks\Config\Datasource;
 
 /**
- * HttpDatasource class
+ * CodedHttpDatasource class
  *
- * Implements the HttpDatasourceInterface to define a generic HTTP datasource.
+ * Extends HttpDatasource to define a HTTP datasource that can be displayed in
+ * the plugin settings.
  *
  * @package remote-data-blocks
  * @since 0.1.0
  */
-abstract class CompatibleHttpDatasource extends HttpDatasource {
+abstract class CodedHttpDatasource extends HttpDatasource {
 	/**
 	 * Provide object representations of the data source for display in plugin
 	 * settings. This allows the data sources defined in code to be viewed without

inc/Editor/BlockManagement/ConfigStore.php

@@ -6,7 +6,7 @@
 
 use RemoteDataBlocks\Logging\LoggerManager;
 use Psr\Log\LoggerInterface;
-use RemoteDataBlocks\Config\Datasource\CompatibleHttpDatasource;
+use RemoteDataBlocks\Config\Datasource\CodedHttpDatasource;
 use RemoteDataBlocks\Config\QueryContext\HttpQueryContext;
 
 use function sanitize_title;
@@ -96,7 +96,7 @@ public static function get_compatible_data_sources(): array {
 
 				$data_source = $query->get_datasource();
 
-				if ( ! $data_source instanceof CompatibleHttpDatasource ) {
+				if ( ! $data_source instanceof CodedHttpDatasource ) {
 					continue;
 				}
 

inc/ExampleApi/Queries/ExampleApiDataSource.php

@@ -2,13 +2,13 @@
 
 namespace RemoteDataBlocks\ExampleApi\Queries;
 
-use RemoteDataBlocks\Config\Datasource\HttpDatasource;
+use RemoteDataBlocks\Config\Datasource\DatasourceInterface;
 
 /**
  * This is a placeholder datasource used only to represent the data source in the
  * settings UI. The actual data loading is implemented by ExampleApiQueryRunner.
  */
-class ExampleApiDataSource extends HttpDatasource {
+class ExampleApiDataSource implements DatasourceInterface {
 	/**
 	 * @inheritDoc
 	 */
@@ -19,14 +19,7 @@ public function get_display_name(): string {
 	/**
 	 * @inheritDoc
 	 */
-	public function get_endpoint(): string {
-		return 'https://example.com/api/v1';
-	}
-
-	/**
-	 * @inheritDoc
-	 */
-	public function get_request_headers(): array {
-		return [];
+	public function get_image_url(): null {
+		return null;
 	}
 }

inc/Integrations/Airtable/AirtableDatasource.php

@@ -2,10 +2,9 @@
 
 namespace RemoteDataBlocks\Integrations\Airtable;
 
-use RemoteDataBlocks\Config\Datasource\CompatibleHttpDatasource;
-use function sanitize_title;
+use RemoteDataBlocks\Config\Datasource\CodedHttpDatasource;
 
-class AirtableDatasource extends CompatibleHttpDatasource {
+class AirtableDatasource extends CodedHttpDatasource {
 	private $tables;
 
 	public function __construct( private string $access_token, private string $base, mixed $tables ) {

inc/Integrations/Shopify/ShopifyDatasource.php

@@ -2,13 +2,13 @@
 
 namespace RemoteDataBlocks\Integrations\Shopify;
 
-use RemoteDataBlocks\Config\Datasource\CompatibleHttpDatasource;
+use RemoteDataBlocks\Config\Datasource\CodedHttpDatasource;
 
 use function plugins_url;
 
 defined( 'ABSPATH' ) || exit();
 
-class ShopifyDatasource extends CompatibleHttpDatasource {
+class ShopifyDatasource extends CodedHttpDatasource {
 	public function __construct( private string $access_token, private string $store_name ) {}
 
 	public function get_store_name(): string {
@@ -18,7 +18,7 @@ public function get_store_name(): string {
 	public function get_display_name(): string {
 		return 'Shopify (' . $this->store_name . ')';
 	}
-	
+
 	public function get_endpoint(): string {
 		return 'https://' . $this->store_name . '.myshopify.com/api/2024-04/graphql.json';
 	}