Spacy API

A Python web API for multilingual text processing using spaCy & Voikko.

Prerequisites

• Azure subscription
• Docker

Development Container

1. Open the project in VS Code
2. Open the Command Palette (Ctrl+Shift+P or Cmd+Shift+P)
3. Select "Dev Containers: Reopen in Container"

Note: For ARM processors, the BLIS_ARCH=generic build argument is required due to BLIS 1.2.0+ dropping ARM/aarch64 support. Without this, the build will fail during dependency installation.

Azure Deployment

1. Login to Azure:

   az login

2. Create a resource group:

   az group create --name spacy-api --location northeurope

3. Deploy the infrastructure using Bicep:

   az deployment group create \
   --resource-group spacy-api \
   --template-file main.bicep \
   --parameters environmentName="prod"

4. After deploying the infrastructure, build and push the Docker image:

   # Get ACR login server
   ACR_NAME=$(az deployment group show \
       --resource-group spacy-api \
       --name main \
       --query properties.outputs.acrLoginServer.value \
       --output tsv | cut -d'.' -f1)
   
   # Login to ACR
   az acr login --name $ACR_NAME
   
   # Build Docker image
   docker build -t ${ACR_NAME}.azurecr.io/spacy-api:latest .
   
   # Build Docker image (ARM)
   docker build -t ${ACR_NAME}.azurecr.io/spacy-api:latest --build-arg BLIS_ARCH=generic .
   
   # Push Docker image
   docker push ${ACR_NAME}.azurecr.io/spacy-api:latest

Updating Infrastructure

When you need to update your infrastructure after making changes to the Bicep files:

1. Preview changes using the what-if operation:

   az deployment group what-if \
   --resource-group spacy-api \
   --template-file main.bicep \
   --parameters environmentName="prod"

2. Apply the changes if the preview looks correct:

   az deployment group create \
   --resource-group spacy-api \
   --template-file main.bicep \
   --parameters environmentName="prod"

Authentication

API Endpoints

API endpoints are protected with Azure API Management subscription keys. Each client needs a valid subscription key provided through Azure API Management service.

To manage API subscriptions using Azure CLI:

• List existing subscriptions

  az rest --method GET \
      --uri "https://management.azure.com/subscriptions/{subscription-id}/resourceGroups/spacy-api/providers/Microsoft.ApiManagement/service/spacy-api-prod/subscriptions?api-version=2022-08-01"

• Create a new subscription for a client

  az rest --method PUT \
      --uri "https://management.azure.com/subscriptions/{subscription-id}/resourceGroups/spacy-api/providers/Microsoft.ApiManagement/service/spacy-api-prod/subscriptions/{client-name}-subscription?api-version=2022-08-01" \
      --body '{
          "properties": {
              "scope": "/products/spacy-product",
              "displayName": "${client-name} Subscription",
              "state": "active"
          }
      }'

• Get subscription keys

  az rest --method GET \
      --uri "https://management.azure.com/subscriptions/{subscription-id}/resourceGroups/spacy-api/providers/Microsoft.ApiManagement/service/spacy-api-prod/subscriptions/{client-name}-subscription?api-version=2022-08-01"

• Regenerate primary key

  az rest --method POST \
      --uri "https://management.azure.com/subscriptions/{subscription-id}/resourceGroups/spacy-api/providers/Microsoft.ApiManagement/service/spacy-api-prod/subscriptions/{client-name}-subscription/regeneratePrimaryKey?api-version=2022-08-01"

• Regenerate secondary key

  az rest --method POST \
      --uri "https://management.azure.com/subscriptions/{subscription-id}/resourceGroups/spacy-api/providers/Microsoft.ApiManagement/service/spacy-api-prod/subscriptions/{client-name}-subscription/regenerateSecondaryKey?api-version=2022-08-01"

Note: Replace {subscription-id} with your Azure subscription ID. You can get it by running:

az account show --query id -o tsv

Test the API with subscription key:

curl -X GET "https://spacy-api-prod.azure-api.net/spacy-api/process?text=Hello%20world" \
    -H "Ocp-Apim-Subscription-Key: your-subscription-key"