REST API Design in CPN

Andrew Zhang

2022.5.25

Category

  • API Style
  • CRUD
  • Configurator API

API Style

API Style

{
  "url": "/distributors/:id/dashboard",
  "response": {
    "activeCustomers": 59,
    "activeSubscriptions": 1163,
    "currentCustomers": 66,
    "currentSubscriptions": 1540,
    "expiringSubscriptions": 1,
    "monthlyTransactions": 76,
    "totalCustomers": 66,
    "totalSubscriptions": 1549
  }
}

API Style

{
  "url": "/dashboard/orgs/:id/summary/services/entity-count",
  "response": {
    "value":207,
    "type":"CUSTOMERS",
    "name":"Customers"
  }
}
{
  "url": "/dashboard/orgs/:id/summary/customers/entity-count",
  "response": {
  	"value":207,
  	"type":"CUSTOMERS",
  	"name":"Customers"
  }
}

API Style

{
  "url": "mgmt/orgs/:id/services?context=PROVIDER&canBeEnabled=true"
}


{
  "url": "/mgmt/orgs/:id/services?context=PROVIDER&canBeEnabled=false"
}

API Style

{
  "url": "/orgs/:id/backing-infra-services"
}


{
  "url": "/distributors/:id/orders/supported-services"
}

CRUD

CRUD

CRUD URI Safe Idempotent
GET Read /offers
/offers/:id
Yes Yes
POST Create /offers No No
PUT Update /offers/:id No Yes
DELETE Delete /offers/:id No Yes

GET

{
  "url": "/distributors/:id/subscriptions/search?pageStart=1&pageLimit=10",
  "method": "POST",
  "payload": {
    "filters": {
      "key": "RESELLER_NAME",
      "value": "media",
      "operator": "LIKE"
    },
    "sorter": {
      "key": "SUBSCRIPTION_END_DATE",
      "operator": "DESC"
    }
  }
}
{
  "url": "/distributors/:id/subscriptions",
  "method": "GET",
  "query": {
    "pageStart": 1,
    "pageLimit": 10,
    "sort": SUBSCRIPTION_END_DATE,desc,
    "filter": RESELLER_NAME=="*media*"
  }
}

POST, PUT

{
  "url": "/distributors/:id/orders/offers/related/search",
  "method": "POST",
  "payload": {
    additionalQuantity: 0,
    billingFrequency: "ANNUAL",
    billingModel: "COMMIT_ONLY",
    billingTerm: "36",
    billingTermUom: "MONTHS",
    currency: "USD",
    customerSegment: "COMMERCIAL",
    dataCenter: "NOT_APPLICABLE",
    description: "VMWARE WORKSPACE ONE STANDARD",
    endDate: "2025-05-16T06:59:59Z",
    hostingType: "MANAGED",
    licenseUnit: "1DU",
    name: "VMWARE WORKSPACE ONE STANDARD",
    offerCategory: "PRIMARY",
    offerConfigGroupId: "acpq_975582230670356480",
    offerReferenceIds: ["92238cac-0c08-44aa-9864-bb684c08f166"],
    offerType: "COMMIT",
    productId: "WSCSTD_TS",
    programOption: "NOT_APPLICABLE",
    purchaseQuantity: 3000,
    region: "NA",
    serviceDefinitionId: "3f2e0417-0ad6-481d-b221-686437701b0e",
    startDate: "2022-05-16T07:00:00Z",
    supportLevel: "BASICSUPPORT",
    tierName: "NOT_APPLICABLE",
    type: "EXPANSION"
  }
}

Relative Object

  • Unique business field
  • Unique ID
  • Partial Object

DELETE

{
  "url": "/orgs/:id/users",
  "method": "DELETE",
  "payload":{
    "users":[
      { "username":"...", "idpId":"..." },
      { "username":"...", "idpId":"..." }
    ]
  }
}
{
  "url": "/orgs/:id/users?ids=1,2,3",
  "method": "DELETE",
}

Error Handling

Client Side Error: 4xx

Server Side Error: 5xx

{
  "url": "/distributors/:id/orders/configurations/preview",
  "method": "POST",
  "statusCode": "200",
  "response":{
    "expansionConfig": {
      configError: [
        {
          "errorCode": "ATTRIBUTE_DEPENDENCY",
          "fieldName": "",
          "message": "endDate for product type ONETIME should be common accross SID"
        }
      ],
      ...
    },
    ...
  }
}
{
  "url": "/distributors/:id/orders/configurations/preview",
  "method": "POST",
  "statusCode": "500",
  "response":{
    "errorCode": "543",
    "message": "endDate for product type ONETIME should be common accross SID",
  }
}

Configurator API

  • Single Responsibility
  • Resource Oriented
  • Config Errors
Made with Slides.com