More doc

Author: cstenac

dataikuapi/dss/apiservice.py

@@ -1,13 +1,32 @@
 import json
 
 class DSSAPIServiceSettings(object):
+    """
+    The settings of an API Service in the API Designer
+
+    Do not create this directly, use :meth:`DSSAPIService.get_settings`
+    """
     def __init__(self, client, project_key, service_id, settings):
         self.client = client
         self.project_key = project_key
         self.service_id = service_id
         self.settings = settings
 
+    def get_raw(self):
+        """
+        Gets the raw settings of this API Service. This returns a reference to the raw settings, not a copy,
+        so changes made to the returned object will be reflected when saving.
+
+        :rtype: dict
+        """
+        return self.settings
+
     def add_prediction_endpoint(self, endpoint_id, saved_model_id):
+        """Adds a new "visual prediction" endpoint to this API service
+
+        :param str endpoint_id: Identifier of the new endpoint to create
+        :param str saved_model_id: Identifier of the saved model (deployed to Flow) to use
+        """
         self.settings["endpoints"].append({
             "id" : endpoint_id,
             "type" : "STD_PREDICTION",
@@ -16,15 +35,16 @@ def add_prediction_endpoint(self, endpoint_id, saved_model_id):
 
     def save(self):
         """Saves back these settings to the API Service"""
-        print("SAVING: %s" % json.dumps(self.settings, indent=2))
         self.client._perform_empty(
                 "PUT", "/projects/%s/apiservices/%s/settings" % (self.project_key, self.service_id),
                 body = self.settings)
 
 
 class DSSAPIService(object):
     """
-    An API Service on the DSS instance
+    An API Service from the API Designer on the DSS instance
+
+    Do not create this directly, use :meth:`dataikuapi.dss.project.DSSProject.get_api_service`
     """
     def __init__(self, client, project_key, service_id):
         self.client = client
@@ -40,24 +60,27 @@ def get_settings(self):
 
     def list_packages(self):
         """
-        List the packages of this API services
+        List the versions of this API service
         
-        Returns:
-            the list of API service packages, each one as a JSON object
+        :returns: a list of dictionaries, with one item per version.
+                  Each dictionary contains at least a 'id' field which is the version identifier
+        :rtype: list of dict
         """
         return self.client._perform_json(
             "GET", "/projects/%s/apiservices/%s/packages" % (self.project_key, self.service_id))
 
     def create_package(self, package_id):
         """
-        Prepare a package of this API service
+        Create a new version of this API service
+
+        :param str package_id: Identifier of the new version to create
         """
         return self.client._perform_empty(
             "POST", "/projects/%s/apiservices/%s/packages/%s" % (self.project_key, self.service_id, package_id))
 
     def delete_package(self, package_id):
         """
-        Delete a package of this API service
+        Delete a version of this API service
         """
         return self.client._perform_empty(
             "DELETE", "/projects/%s/apiservices/%s/packages/%s" % (self.project_key, self.service_id, package_id))

dataikuapi/dss/project.py

@@ -472,10 +472,11 @@ def list_api_services(self):
 
     def create_api_service(self, service_id):
         """
-        Create a new API service, and returns a handle to interact with it
+        Create a new API service, and returns a handle to interact with it. The newly-created
+        service does not have any endpoint.
 
         :param str service_id: the ID of the API service to create
-        :returns: A :class:`dataikuapi.dss.dataset.DSSAPIService` API Service handle
+        :returns: A :class:`~dataikuapi.dss.dataset.DSSAPIService` API Service handle
         """
         self.client._perform_empty(
             "POST", "/projects/%s/apiservices/%s" % (self.project_key, service_id))
@@ -484,17 +485,14 @@ def create_api_service(self, service_id):
 
     def get_api_service(self, service_id):
         """
-        Get a handle to interact with a specific API service
+        Get a handle to interact with a specific API Service from the API Designer
 
-        Args:
-            service_id: the ID of the desired API service
-
-        Returns:
-            A :class:`dataikuapi.dss.dataset.DSSAPIService` API Service handle
+        :param str service_id: The identifier of the API Designer API Service to retrieve
+        :returns: A handle to interact with this API Service
+        :rtype: :class:`~dataikuapi.dss.dataset.DSSAPIService` API Service handle
         """
         return DSSAPIService(self.client, self.project_key, service_id)
 
-
     ########################################################
     # Bundles / Export (Design node)
     ########################################################