Conventions

Object IDs

Upshift-generated identifiers contain the type of an object and a globally unique identifier. This enables humans to easily understand what kind of object an ID refers to.

Here’s an example of an app ID:

  app_01jhb4nyd9fahvpca24wtwfcxq
  └──┘ └────────────────────────┘
  type    uuid suffix (base32)

Upshift Object IDs follow the TypeID spec.

Updates

We use HTTP PATCH requests to update resources. The behavior of PATCH is to only update the fields that are provided in the request body.

To remove an optional field, the client should send the field with a value of null. Note that attempting to set a required field to null will result in a 422 UnprocessableContentError error.

Example PATCH /developer/apps/v1/:id request body:

1
{
2
    // This will result in a 422 error, as name cannot be set to null
3
    "name": null,
4
    "listingInfo": {
5
        // Update the short description field
6
        "shortDescription": "Updated short description",
7
        // Remove the optional long description field
8
        "longDescription": null
9
    }
10
    // All omitted app fields will be unchanged
11
}

Pagination

We use pagination in our API to make sure that we don’t return too much data at once. Our list endpoint shapes extend the Page type:

1
Page:
2
    nextCursor: optional<string>
3
    prevCursor: optional<string>

Unions

We use unions to represent a type that can be one of several different types. When a union shape is used, our union discriminant will always be the type field unless otherwise specified.

As mentioned in Breaking Changes, we expect that it is a non-breaking change to add a new union member to a union type. This means that if you handle a union field in a response, we expect you to gracefully handle an _other case. This allows us to better serve and improve our APIs at a quick velocity without breaking your code.