Our last blog was all about how to monetize your API on Fortellis. This month, we’re looking at common mistakes to avoid if you want to maximize the effectiveness and profitability of your API on Fortellis.

Hey, we all do these things from time to time. Developing an API is difficult, complex work. That’s why each of us can benefit from brushing up on common pitfalls — even if some of them make us say “duh.” Check out our list below and keep these points in mind as you build your API:

When concepting and developing your API, you should NOT:

1. Mess up your versioning

APIs are contracts between the developer and the consumer of the API. When you hold true to the contract as a developer, you help the consuming application continue to work as expected. Adding new endpoints doesn’t require a new major version for the API, but changing the URI structure, for example, could be detrimental. It may be easier to put more effort into API design. If you plan ahead, you can keep things running smoothly so breaking changes isn’t required.

2. Overlook revenue goals

Most APIs live within the context of a business seeking to provide returns to shareholders. Without a tie to revenue, businesses may abandon your product, which means your development time was wasted effort. To ensure revenue goals are achievable, select a reasonable target in terms of the number of transactions you wish to reach. Prices can always be adjusted along with the delivery of business value.

3. Provide unclear documentation

You knew there’d be something here about documentation, right? If you want to keep things as crystal clear as possible, writing the documentation during API architecture could give you a good head start. Don’t be afraid to ask for technical writing assistance during your design sprints.

4. Chain dependent API calls together in a weird sequence without proper instruction

Don’t assume all developers understand the order of operations for a common industry workflow. We all have backgrounds working within different industries, so it’s always better to be explicit than complicit. If all else fails, you can use a diagram to explain sequential tasks.

5. Use improper methods (PUT or POST when you should be using a GET request)

Consider brushing up by reading the spec on http methods and what types of operations and modifications are permissible and expected. The state of the resource represented in your API might change naturally, but not because of a GET request made by your API consumer. If that’s the case, you could be using the wrong method.

6. Adopt a “throw it over the wall” design mentality

Think of the developer on the application side who will be implementing your API. Well-designed APIs are more likely to be adopted and used. Otherwise, why put in the work to create an API in the first place? The more you can put yourself in the application developer’s shoes and make their experience as seamless as possible, the more use and monetization you can expect from your API.

7. Create an omnibus API set instead of an API designed for a specific workflow

Long processes requiring chained sequences of dozens of API calls might be overkill. Consider breaking up a larger API into separate workflows you can document, define and cover within your API set. Getting rid of the domain-specific details and focusing on workflow can make it easier for new industry players to adopt and use your API. Instead of cramming dozens of endpoints into a single API, use your design process to consolidate and break up these APIs in the name of functionality. If you think it’s too complicated, it probably is.

8. Develop an API set so complicated that a salesperson can’t explain the functionality

If it’s too complex, the accompanying sales materials won’t be able to encompass or outline how it works. Nobody’s going to buy something if they don’t understand how or why they should use it. Usability testing could help you understand how the API will be used in the real world. An API is not purely a conceptual construct; it’s meant to be used functionally.

Now let’s get this show on the road.

You know the dos and don’ts. So, what are you waiting for? Click over to our APIs tab to get started on publishing one of your own.

Authored on Tue, 06/09/2020 - 13:36