# FirstMile Label API Migration Guide: SOAP to REST

This guide helps users transition from the legacy FirstMile SOAP API to the new REST API.

## Overview

- All SOAP methods are now available as REST endpoints
- Request and response models are mapped to OpenAPI schemas
- **Key Change**: Both domestic and international operations now use unified request models
- Field names follow camelCase convention for JSON
- OAuth 2.0 Bearer token authentication replaces SOAP credentials


## Endpoint Mapping

| SOAP Method | REST Endpoint | HTTP Method | Request Model | Response Model |
|  --- | --- | --- | --- | --- |
| GetLabel(DhlLabelRequest) | /api/v1/label | POST | FirstMileRequest | LabelResponse |
| GetInternationalLabel(InternationalLabelRequest) | /api/v1/label | POST | FirstMileRequest | LabelResponse |
| CancelDomesticLabel | /api/v1/label/{trackingNumber}/{techPartnerId} | DELETE | Path params | 200 OK or 404 with errors |
| CancelInternationalLabel | /api/v1/label/{trackingNumber}/{techPartnerId} | DELETE | Path params | 200 OK or 404 with errors |
| CloseDomesticShippingDay | /api/v1/label/CloseDay | POST | CloseShippingDayRequest | CloseShippingDayResponse |
| CloseInternationalShippingDay | /api/v1/label/CloseDay | POST | CloseShippingDayRequest | CloseShippingDayResponse |
| GetRate(DomesticRateRequest) | /api/v1/rate | POST | FirstMileRequest | RateResponse |
| GetInternationalRate(InternationalRateRequest) | /api/v1/rate | POST | FirstMileRequest | RateResponse |
| GetRates(DomesticRatesRequest) | /api/v1/rate/Shop | POST | FirstMileRequest | RatesResponse |
| GetInternationalRates(InternationalRatesRequest) | /api/v1/rate/Shop | POST | FirstMileRequest | RatesResponse |
| GetMeters | /api/v1/meter/{techPartnerId} | GET | Path param | MetersResponse |
| GetMeterBalance | /api/v1/meter/{id}/{techPartnerId} | GET | Path params | MetersResponse |
| AddFundsToMeter | /api/v1/meter/AddFunds | POST | AddFundsRequest | AddFundsResponse |


## Field Mapping

### Core Request Fields

| SOAP Field | REST Field | Notes |
|  --- | --- | --- |
| FromAddress | fromAddress | Address object |
| ShipToAddress | toAddress | Address object |
| LabelType | shippingServiceEnum | **Preferred**: Use enum version |
| LabelType | shippingService | **Legacy**: String version (deprecated) |
| PackageDetail | packages | Array of Package objects |
| WeightOz | shipmentWeightOz | Total shipment weight in ounces |
| CustomsData | customsData | For international shipments |
| LabelImageFormat | labelImageFormatEnum | **Preferred**: Enum version |
| LabelSize | labelImageSizeEnum | Thermal label stock size |
| AncillaryEndorsement | ancillaryEndorsementEnum | USPS endorsement |
| SecondaryAncillaryEndorsement | secondaryEndorsementEnum | Secondary USPS endorsement |
| Incoterms | internationalDutyTermsEnum | Customs duties terms |
| FutureShipmentDate | futureShipmentDate | ISO 8601 datetime |
| RequestId | requestId | Echoed in response |


## Enum Value Changes

### ShippingService (LabelType)

Most enum values are preserved but follow consistent naming:

- SOAP: `DhlSmParcelsGround`
- REST: `DhlSm_Parcels_Ground`
- SOAP: `USPSPriorityMailPackage`
- REST: `USPS_Priority_Mail_Package`


## Example Migration

### REST Label Request


```http
POST /api/v1/label
Authorization: Bearer <JWT_TOKEN>
Content-Type: application/json

{
  "techPartnerId": "PARTNER123",
  "fromAddress": {
    "name": "John Doe",
    "address1": "123 Main St",
    "city": "Anytown",
    "state": "CA",
    "postalCode": "12345"
  },
  "toAddress": {
    "name": "Jane Smith", 
    "address1": "456 Oak Ave",
    "city": "Other City",
    "state": "NY",
    "postalCode": "67890"
  },
  "shippingServiceEnum": "FirstMile_Ground",
  "shipmentWeightOz": 16,
  "labelImageFormatEnum": "Png",
  "packages": [
    {
      "weight": {
        "weightOz": 16,
        "weightType": "Actual"
      }
    }
  ]
}
```

## Support Resources

- OpenAPI/Swagger documentation: `/swagger/index.html`
- Test environment: `https://labelserver-test.firstmile.com`
- Production environment: `https://labelserver.firstmile.com`