Overview

Deploy an API

Warning

Deploying Spark models as APIs is not currently supported in Platform version 5.0.

When you deploy an API, a dedicated service is created with your project code and dependencies, and you specify the script and function that powers the endpoint. Your model will accept JSON object payloads as inputs; those values are passed to your function, and then the results are returned back to the requestor. For example, if you deployed this function:

def addXY(x, y):
    return x + y

then calling the API with {'x':2,'y':3} will return 5.

To deploy a model API, select Deploy an API from the actions menu in the upper right-hand corner below your avatar. Enter the following information to complete configuration:

  • Name and description: Enter your API’s name (limit 55 characters) and description (limit 140 characters). These will be displayed on the project’s Output page to help users find your API.
  • Branch: Indicate the branch of your repo that will be loaded into the deployed API’s container. The entire repo will be loaded into the container, not just the file to be deployed.
  • Model path: Enter the name of the file that contains the function to be deployed.
  • Language: Select the language that the model is written in.
  • Compute Resource: Choose the size of the hardware where your API will be deployed.
  • Environment and Additional Requirements: Determine the environment and any additional dependencies that are needed for your model to run.
  • The function: Fill in the specific function (which must be in the file you chose above) that you wish to deploy. This function will take inputs from each incoming API request.
  • Example data: Once your API is deployed, it will have an API page where users can view information about it. That page includes a section for trying sample data and seeing what the API would return with those inputs. If you supply example data in this step, it will be populated in the sample data section of your API page by default. Your sample data must be a valid JSON object.
  • Commit message: A short message to help identify this version of the API.
../_images/Deploy-an-API-basic.png

Warning

When you deploy a script, the file must be in the root of the project. Deploying files in sub-folders is currently not supported.

Warning

Per good engineering practices, ensure there are no spaces in your file or folder names.

Warning

Your function’s output is converted to JSON, so only data types and structures that can be “JSONified” may be returned. Complex data structures like NumPy arrays should be converted to lists using the my_array.tolist() function. In addition, NumPy data types such as numpy.float64 and others should be converted to the native Python equivalents. For example, convert a NumPy float to a Python native type with float(my_numpy_float).

Call an API

Once you have deployed an API, you can see information about it on its API page (in the project Outputs tab). On this page, you can run a sample call or find snippets for testing the API endpoint from your own code.

../_images/API-details.png

Copy/paste one of the cURL, node.js, or Python snippets your own code or command line to call the model.

In the code snippets, you’ll find an API access token, which acts as a limited-access password to your endpoint. Share this token only with those you wish to call your API.

Manage an API

From the API page you can undeploy API versions. This action will shut down the container running the model. You can re-deploy later, which will re-create the container.

You may delete an API version, which shuts down the container and deletes the API image from the Platform’s database. You may not undo a delete, but you may redeploy the same code after deleting a version.

To delete all versions of a Model API, visit the More Options tab on the API page.

../_images/Delete-an-API-option.png