To make life for developers easier, be explicit in what exactly is being returned. In the Stripe API, we have an object field in the response that makes it abundantly clear what we’re working with. For example, the API route

/v1/customers/:customer/payment_methods/:payment_method

Enter fullscreen mode

Exit fullscreen mode

returns a PaymentMethod... See more

Subscription.status={"active", "canceled"}

Enter fullscreen mode

Exit fullscreen mode

A single field tells us in plain language what the status of the object is by using enums instead of booleans. Another upside is the extensibility and future-proofing that this technique gives us. If we go back to our previous example of adding a “pause” mechanic,... See more

Use nested objects for future extensibility

A follow on from the previous tip: try to logically group fields together. The following:

customer.address = {

line1: "Main Street 123",

city: "San Francisco",

postal_code: "12345"

};

Enter fullscreen mode

Exit fullscreen mode

is much cleaner than:

customer.address_line1 = "Main street 123";

customer.address_city... See more