wikidata_adaptor 1.0.0

data/lib/wikidata_adaptor/rest_api/statements.rb

@@ -0,0 +1,153 @@
+# frozen_string_literal: true
+
+module WikidataAdaptor
+  class RestApi
+    # https://doc.wikimedia.org/Wikibase/master/js/rest-api/#/statements
+    module Statements
+      # Retrieve Statements from an Item.
+      #
+      # Optional filter:
+      #   params[:property] => property ID (e.g., "P31")
+      def get_item_statements(item_id, params = { property: nil })
+        query = params[:property] ? "?property=#{CGI.escape(params[:property])}" : ""
+        get_json("#{endpoint}/v1/entities/items/#{CGI.escape(item_id)}/statements#{query}")
+      end
+
+      # Retrieve a single Statement from an Item.
+      def get_item_statement(item_id, statement_id)
+        get_json("#{endpoint}/v1/entities/items/#{CGI.escape(item_id)}/statements/#{statement_id}")
+      end
+
+      # Add a Statement to an Item.
+      #
+      # @param [String] item_id The ID of the Item.
+      # @param [Hash] payload Statement and edit metadata.
+      #
+      # @return [Hash] The newly created Statement.
+      def post_item_statement(item_id, payload)
+        post_json("#{endpoint}/v1/entities/items/#{CGI.escape(item_id)}/statements", payload)
+      end
+
+      # Retrieve a single Statement (global).
+      def get_statement(statement_id)
+        get_json("#{endpoint}/v1/statements/#{statement_id}")
+      end
+
+      # Retrieve Statements from a Property.
+      def get_property_statements(property_id)
+        get_json("#{endpoint}/v1/entities/properties/#{CGI.escape(property_id)}/statements")
+      end
+
+      # Retrieve a single Statement from a Property.
+      def get_property_statement(property_id, statement_id)
+        get_json("#{endpoint}/v1/entities/properties/#{CGI.escape(property_id)}/statements/#{statement_id}")
+      end
+
+      # Add a Statement to a Property.
+      #
+      # @param [String] property_id The ID of the Property.
+      # @param [Hash] payload Statement and edit metadata.
+      #
+      # @return [Hash] The newly created Statement.
+      def post_property_statement(property_id, payload)
+        post_json("#{endpoint}/v1/entities/properties/#{CGI.escape(property_id)}/statements", payload)
+      end
+
+      # Replace a Statement on an Item.
+      #
+      # @param [String] item_id The ID of the Item.
+      # @param [String] statement_id The Statement ID.
+      # @param [Hash] payload Statement and edit metadata.
+      #
+      # @return [Hash] The replaced Statement.
+      def put_item_statement(item_id, statement_id, payload)
+        put_json("#{endpoint}/v1/entities/items/#{CGI.escape(item_id)}/statements/#{statement_id}", payload)
+      end
+
+      # Replace a Statement on a Property.
+      #
+      # @param [String] property_id The ID of the Property.
+      # @param [String] statement_id The Statement ID.
+      # @param [Hash] payload Statement and edit metadata.
+      #
+      # @return [Hash] The replaced Statement.
+      def put_property_statement(property_id, statement_id, payload)
+        put_json("#{endpoint}/v1/entities/properties/#{CGI.escape(property_id)}/statements/#{statement_id}", payload)
+      end
+
+      # Replace a Statement (global).
+      #
+      # @param [String] statement_id The Statement ID.
+      # @param [Hash] payload Statement and edit metadata.
+      #
+      # @return [Hash] The replaced Statement.
+      def put_statement(statement_id, payload)
+        put_json("#{endpoint}/v1/statements/#{statement_id}", payload)
+      end
+
+      # Apply JSON Patch operations to a Statement on an Item.
+      #
+      # @param [String] item_id The ID of the Item.
+      # @param [String] statement_id The Statement ID.
+      # @param [Hash] payload JSON Patch operations and edit metadata.
+      #
+      # @return [Hash] The updated Statement.
+      def patch_item_statement(item_id, statement_id, payload)
+        patch_json("#{endpoint}/v1/entities/items/#{CGI.escape(item_id)}/statements/#{statement_id}", payload)
+      end
+
+      # Apply JSON Patch operations to a Statement on a Property.
+      #
+      # @param [String] property_id The ID of the Property.
+      # @param [String] statement_id The Statement ID.
+      # @param [Hash] payload JSON Patch operations and edit metadata.
+      #
+      # @return [Hash] The updated Statement.
+      def patch_property_statement(property_id, statement_id, payload)
+        patch_json("#{endpoint}/v1/entities/properties/#{CGI.escape(property_id)}/statements/#{statement_id}", payload)
+      end
+
+      # Apply JSON Patch operations to a Statement (global).
+      #
+      # @param [String] statement_id The Statement ID.
+      # @param [Hash] payload JSON Patch operations and edit metadata.
+      #
+      # @return [Hash] The updated Statement.
+      def patch_statement(statement_id, payload)
+        patch_json("#{endpoint}/v1/statements/#{statement_id}", payload)
+      end
+
+      # Delete a Statement from an Item.
+      #
+      # @param [String] item_id The ID of the Item.
+      # @param [String] statement_id The Statement ID.
+      # @param [Hash] payload Edit metadata (comment).
+      #
+      # @return [String] Confirmation message.
+      def delete_item_statement(item_id, statement_id, payload)
+        delete_json("#{endpoint}/v1/entities/items/#{CGI.escape(item_id)}/statements/#{statement_id}", payload)
+      end
+
+      # Delete a Statement from a Property.
+      #
+      # @param [String] property_id The ID of the Property.
+      # @param [String] statement_id The Statement ID.
+      # @param [Hash] payload Edit metadata (comment).
+      #
+      # @return [String] Confirmation message.
+      def delete_property_statement(property_id, statement_id, payload)
+        delete_json("#{endpoint}/v1/entities/properties/#{CGI.escape(property_id)}/statements/#{statement_id}", payload)
+      end
+
+      # Delete a Statement (global).
+      #
+      # @param [String] statement_id The Statement ID.
+      # @param [Hash] payload Edit metadata (comment).
+      #
+      # @return [String] Confirmation message.
+      def delete_statement(statement_id, payload)
+        delete_json("#{endpoint}/v1/statements/#{statement_id}", payload)
+      end
+    end
+  end
+end

data/lib/wikidata_adaptor/rest_api.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+# Adapter for the wikibase REST API
+#
+# @see https://doc.wikimedia.org/Wikibase/master/js/rest-api/
+module WikidataAdaptor
+  # Wikidata REST API class
+  class RestApi < ApiAdaptor::Base
+    require_relative "rest_api/open_api_document"
+    require_relative "rest_api/items"
+    require_relative "rest_api/sitelinks"
+    require_relative "rest_api/properties"
+    require_relative "rest_api/labels"
+    require_relative "rest_api/descriptions"
+    require_relative "rest_api/aliases"
+    require_relative "rest_api/statements"
+    require_relative "rest_api/property_data_types"
+    require_relative "rest_api/search_item"
+    require_relative "rest_api/search_property"
+    include WikidataAdaptor::RestApi::OpenApiDocument
+    include WikidataAdaptor::RestApi::Items
+    include WikidataAdaptor::RestApi::Sitelinks
+    include WikidataAdaptor::RestApi::Properties
+    include WikidataAdaptor::RestApi::Labels
+    include WikidataAdaptor::RestApi::Descriptions
+    include WikidataAdaptor::RestApi::Aliases
+    include WikidataAdaptor::RestApi::Statements
+    include WikidataAdaptor::RestApi::PropertyDataTypes
+    include WikidataAdaptor::RestApi::SearchItem
+    include WikidataAdaptor::RestApi::SearchProperty
+  end
+end

data/lib/wikidata_adaptor/test_helpers/rest_api/aliases.rb

@@ -0,0 +1,229 @@
+# frozen_string_literal: true
+
+module WikidataAdaptor
+  module TestHelpers
+    module RestApi
+      # WebMock stubs for Wikibase REST API alias endpoints
+      module Aliases
+        ######################################
+        # GET /v1/entities/items/:item_id/aliases
+        ######################################
+        def stub_get_item_aliases(item_id)
+          stub_rest_api_request(
+            :get,
+            "/v1/entities/items/#{item_id}/aliases",
+            response_body: {
+              en: [
+                "Douglas Noel Adams",
+                "Douglas Noël Adams"
+              ],
+              fr: [
+                "Douglas Noel Adams"
+              ]
+            }
+          )
+        end
+
+        #####################################################
+        # GET /v1/entities/items/:item_id/aliases/:language_code
+        #####################################################
+        def stub_get_item_alias(item_id, language_code)
+          stub_rest_api_request(
+            :get,
+            "/v1/entities/items/#{item_id}/aliases/#{language_code}",
+            response_body: [
+              "Douglas Noel Adams",
+              "Douglas Noël Adams"
+            ]
+          )
+        end
+
+        ############################################################
+        # POST /v1/entities/items/:item_id/aliases/:language_code
+        ############################################################
+        def stub_post_item_aliases(item_id, language_code, payload, response_body: nil)
+          stub_rest_api_request(
+            :post,
+            "/v1/entities/items/#{item_id}/aliases/#{language_code}",
+            response_status: 200,
+            with: { body: payload.to_json },
+            response_body: response_body || ["Douglas Noel Adams", "Douglas Noël Adams"]
+          )
+        end
+
+        # Stub POST item aliases request returning 201 Created
+        #
+        # @param [String] item_id The item ID
+        # @param [String] language_code The language code
+        # @param [Hash] payload The request payload
+        # @param [Array<String>, nil] response_body Optional custom response
+        #
+        # @return [WebMock::RequestStub]
+        def stub_post_item_aliases_created(item_id, language_code, payload, response_body: nil)
+          stub_rest_api_request(
+            :post,
+            "/v1/entities/items/#{item_id}/aliases/#{language_code}",
+            response_status: 201,
+            with: { body: payload.to_json },
+            response_body: response_body || ["Douglas Noel Adams", "Douglas Noël Adams"]
+          )
+        end
+
+        # Stub POST item aliases request returning 500 error
+        #
+        # @param [String] item_id The item ID
+        # @param [String] language_code The language code
+        # @param [Hash] payload The request payload
+        #
+        # @return [WebMock::RequestStub]
+        def stub_post_item_aliases_unexpected_error(item_id, language_code, payload)
+          stub_rest_api_request(
+            :post,
+            "/v1/entities/items/#{item_id}/aliases/#{language_code}",
+            response_status: 500,
+            with: { body: payload.to_json },
+            response_body: {
+              code: "unexpected-error",
+              message: "Unexpected Error"
+            }
+          )
+        end
+
+        ########################################
+        # GET /v1/entities/properties/:property_id/aliases
+        ########################################
+        def stub_get_property_aliases(property_id)
+          stub_rest_api_request(
+            :get,
+            "/v1/entities/properties/#{property_id}/aliases",
+            response_body: {
+              en: ["is a"],
+              fr: ["est un"]
+            }
+          )
+        end
+
+        ########################################################
+        # GET /v1/entities/properties/:property_id/aliases/:language_code
+        ########################################################
+        def stub_get_property_alias(property_id, language_code)
+          stub_rest_api_request(
+            :get,
+            "/v1/entities/properties/#{property_id}/aliases/#{language_code}",
+            response_body: ["is a"]
+          )
+        end
+
+        ################################################################
+        # POST /v1/entities/properties/:property_id/aliases/:language_code
+        ################################################################
+        def stub_post_property_aliases(property_id, language_code, payload, response_body: nil)
+          stub_rest_api_request(
+            :post,
+            "/v1/entities/properties/#{property_id}/aliases/#{language_code}",
+            response_status: 200,
+            with: { body: payload.to_json },
+            response_body: response_body || ["is a", "is an"]
+          )
+        end
+
+        # Stub POST property aliases request returning 201 Created
+        #
+        # @param [String] property_id The property ID
+        # @param [String] language_code The language code
+        # @param [Hash] payload The request payload
+        # @param [Array<String>, nil] response_body Optional custom response
+        #
+        # @return [WebMock::RequestStub]
+        def stub_post_property_aliases_created(property_id, language_code, payload, response_body: nil)
+          stub_rest_api_request(
+            :post,
+            "/v1/entities/properties/#{property_id}/aliases/#{language_code}",
+            response_status: 201,
+            with: { body: payload.to_json },
+            response_body: response_body || ["is a", "is an"]
+          )
+        end
+
+        # Stub POST property aliases request returning 500 error
+        #
+        # @param [String] property_id The property ID
+        # @param [String] language_code The language code
+        # @param [Hash] payload The request payload
+        #
+        # @return [WebMock::RequestStub]
+        def stub_post_property_aliases_unexpected_error(property_id, language_code, payload)
+          stub_rest_api_request(
+            :post,
+            "/v1/entities/properties/#{property_id}/aliases/#{language_code}",
+            response_status: 500,
+            with: { body: payload.to_json },
+            response_body: {
+              code: "unexpected-error",
+              message: "Unexpected Error"
+            }
+          )
+        end
+
+        ###########################################
+        # PATCH /v1/entities/items/:item_id/aliases
+        ###########################################
+        def stub_patch_item_aliases(item_id, payload, response_body: nil)
+          stub_rest_api_request(
+            :patch,
+            "/v1/entities/items/#{item_id}/aliases",
+            with: { body: payload.to_json },
+            response_body: response_body || {
+              en: ["Douglas Noel Adams", "Douglas Noël Adams", "DNA"],
+              fr: ["Douglas Noel Adams"]
+            }
+          )
+        end
+
+        # Stub PATCH item aliases request returning 500 error
+        #
+        # @param [String] item_id The item ID
+        # @param [Hash] payload The request payload
+        #
+        # @return [WebMock::RequestStub]
+        def stub_patch_item_aliases_unexpected_error(item_id, payload)
+          stub_rest_api_request(
+            :patch,
+            "/v1/entities/items/#{item_id}/aliases",
+            response_status: 500,
+            with: { body: payload.to_json },
+            response_body: { code: "unexpected-error", message: "Unexpected Error" }
+          )
+        end
+
+        #################################################
+        # PATCH /v1/entities/properties/:property_id/aliases
+        #################################################
+        def stub_patch_property_aliases(property_id, payload, response_body: nil)
+          stub_rest_api_request(
+            :patch,
+            "/v1/entities/properties/#{property_id}/aliases",
+            with: { body: payload.to_json },
+            response_body: response_body || { en: ["is a", "is an"], fr: ["est un"] }
+          )
+        end
+
+        # Stub PATCH property aliases request returning 500 error
+        #
+        # @param [String] property_id The property ID
+        # @param [Hash] payload The request payload
+        #
+        # @return [WebMock::RequestStub]
+        def stub_patch_property_aliases_unexpected_error(property_id, payload)
+          stub_rest_api_request(
+            :patch,
+            "/v1/entities/properties/#{property_id}/aliases",
+            response_status: 500,
+            with: { body: payload.to_json },
+            response_body: { code: "unexpected-error", message: "Unexpected Error" }
+          )
+        end
+      end
+    end
+  end
+end