Merge pull request #2675 from crugas/update_api_endpoints_doc

Update various api endpoints documentation

backend/app/controllers/date_calculator.rb

@@ -1,21 +1,64 @@
 class ArchivesSpaceService < Sinatra::Base
 
   Endpoint.get('/date_calculator')
-  .description("Calculate the dates of an archival object tree")
-  .params(["record_uri", String, "The uri of the object"],
-          ["label", String, "The date label to filter on", :optional => true])
-  .permissions([])
-  .returns([200, "Calculation results"]) \
-  do
-    parsed = JSONModel.parse_reference(params[:record_uri])
+    .description("Calculate the dates of an archival object tree")
+    .example("shell") do
+      <<~SHELL
+        curl -s -F password="admin" "http://localhost:8089/users/admin/login"
+        # Replace "admin" with your password and "http://localhost:8089/users/admin/login" with your ASpace API URL
+        # followed by "/users/{your_username}/login"
 
-    RequestContext.open(:repo_id => JSONModel(:repository).id_for(parsed[:repository])) do
-      raise AccessDeniedException.new unless current_user.can?(:view_repository)
+        set SESSION="session_id"
+        # If using Git Bash, replace set with export
 
-      obj = Kernel.const_get(parsed[:type].to_s.camelize)[parsed[:id]]
-      date_cal = DateCalculator.new(obj, params[:label])
-      json_response(date_cal.to_hash)
+        curl -H "X-ArchivesSpace-Session: $SESSION" //
+        "http://localhost:8089/date_calculator?record_uri=/repositories/4/archival_objects/336361"
+        # Replace "http://localhost:8089" with your ASpace API URL and /repositories/4/archival_objects/336361 with the 
+        # URI of the archival object
+      SHELL
+    end
+    .example("python") do
+      <<~PYTHON
+        from asnake.client import ASnakeClient  # import the ArchivesSnake client
+        
+        client = ASnakeClient(baseurl="http://localhost:8089", username="admin", password="admin")
+        # Replace http://localhost:8089 with your ArchivesSpace API URL and admin for your username and password
+        
+        client.authorize()  # authorizes the client
+        
+        calc_dates = client.get("date_calculator", params={"record_uri": "/repositories/4/archival_objects/336361"})
+        # Replace "/repositories/4/archival_objects/336361" with the archival object URI
+        
+        print(calc_dates.json())
+        # Output (dict): {'object':
+        #                  {'uri': '/repositories/4/archival_objects/336361', 
+        #                   'jsonmodel_type': 'archival_object', 
+        #                   'title': 'Barrow, Middleton Pope. Papers', 
+        #                   'id': 336361}, 
+        #                 'resource': 
+        #                  {'uri': '/repositories/4/resources/1820', 
+        #                   'title': 'E. Merton Coulter manuscript collection II'}, 
+        #                   'label': None, 
+        #                   'min_begin_date': '1839-01-01', 
+        #                   'min_begin': '1839', 
+        #                   'max_end_date': '1903-12-31', 
+        #                   'max_end': '1903'}
+      PYTHON
+    end
+    .params(["record_uri", String, "The uri of the object"],
+            ["label", String, "The date label to filter on", :optional => true])
+    .permissions([])
+    .returns([200, "Calculation results"]) \
+    do
+      parsed = JSONModel.parse_reference(params[:record_uri])
+
+      RequestContext.open(:repo_id => JSONModel(:repository).id_for(parsed[:repository])) do
+        raise AccessDeniedException.new unless current_user.can?(:view_repository)
+
+        obj = Kernel.const_get(parsed[:type].to_s.camelize)[parsed[:id]]
+        date_cal = DateCalculator.new(obj, params[:label])
+        json_response(date_cal.to_hash)
+      end
     end
-  end
 
 end

backend/app/controllers/extent_calculator.rb

@@ -1,7 +1,8 @@
 class ArchivesSpaceService < Sinatra::Base
 
   Endpoint.get('/extent_calculator')
-  .description("Calculate the extent of an archival object tree")
+  .description("Calculate the extent of an archival object tree. Allowed units include: inches, feet, centimeters,
+                meters.")
   .params(["record_uri", String, "The uri of the object"],
           ["unit", String, "The unit of measurement to use", :optional => true])
   .permissions([])

backend/app/controllers/external_id.rb

@@ -2,6 +2,40 @@ class ArchivesSpaceService < Sinatra::Base
 
   Endpoint.get('/by-external-id')
     .description("List records by their external ID(s)")
+    .example("shell") do
+      <<~SHELL
+        curl -s -F password="admin" "http://localhost:8089/users/admin/login"
+        # Replace "admin" with your password and "http://localhost:8089/users/admin/login" with your ASpace API URL
+        # followed by "/users/{your_username}/login"
+  
+        set SESSION="session_id"
+        # If using Git Bash, replace set with export
+  
+        curl -H "X-ArchivesSpace-Session: $SESSION" "http://localhost:8089/by-external-id?eid='3854'&type[]=resource"
+        # Replace "http://localhost:8089" with your ASpace API URL, '3854' with the external id you are searching for, 
+        # and type[]=resource with the type of record you want to search for (optional)
+      SHELL
+    end
+    .example("python") do
+      <<~PYTHON
+        from asnake.client import ASnakeClient  # import the ArchivesSnake client
+        
+        client = ASnakeClient(baseurl="http://localhost:8089", username="admin", password="admin")
+        # Replace http://localhost:8089 with your ArchivesSpace API URL and admin for your username and password
+        
+        client.authorize()  # authorizes the client
+        
+        find_eid = client.get("by-external-id", params={"eid": "3854", "type[]": "resource"})
+        # Replace "3854" with the external id and "resource" with the type of record(s) you want to search - this is 
+        # optional
+        
+        print(find_eid.json())
+        # Output (dict): the JSON for the record returned. Other outputs include:
+        # 303 – A redirect to the URI named by the external ID (if there’s only one)
+        # 300 – A JSON-formatted list of URIs if there were multiple matches
+        # 404 – No external ID matched
+      PYTHON
+    end
     .permissions([:view_all_records])
     .params(["eid", String, "An external ID to find"],
             ["type",

backend/app/controllers/version.rb

@@ -2,6 +2,36 @@ class ArchivesSpaceService < Sinatra::Base
 
   Endpoint.get('/version')
     .description("Get the ArchivesSpace application version")
+    .example("shell") do
+      <<~SHELL
+        curl -s -F password="admin" "http://localhost:8089/users/admin/login"
+        # Replace "admin" with your password and "http://localhost:8089/users/admin/login" with your ASpace API URL
+        # followed by "/users/{your_username}/login"
+  
+        set SESSION="session_id"
+        # If using Git Bash, replace set with export
+  
+        curl -H "X-ArchivesSpace-Session: $SESSION" "http://localhost:8089/version"
+        # Replace "http://localhost:8089" with your ASpace API URL
+      SHELL
+    end
+    .example("python") do
+    <<~PYTHON
+      from asnake.client import ASnakeClient  # import the ArchivesSnake client
+      
+      client = ASnakeClient(baseurl="http://localhost:8089", username="admin", password="admin")
+      # Replace http://localhost:8089 with your ArchivesSpace API URL and admin for your username and password
+      
+      client.authorize()  # authorizes the client
+      
+      aspace_version = client.get("/version")
+      # Retrieves the ArchivesSpace version
+      
+      print(aspace_version.content.decode())
+      # Output (str): ArchivesSpace (v3.1.1)
+      # Use .content.decode() to print the response since .json() returns a JSON decoding error
+    PYTHON
+  end
     .params()
     .permissions([])
     .returns([200, "ArchivesSpace (version)"]) \