Best Practices for API Development

APIs have been in use for decades; however, the best practices for APIs are constantly evolving and changing with the demands of technology. Businesses have discovered that through the use of APIs they can interface with their business, monetize digital assets, extend value with partners, and connect customers across devices and business channels. With so much value found in APIs, the IT consulting experts at Pittsburgh’s Savvior want to keep you up to date so your business can take full advantage.

Where APIs can fall short

The IT consulting experts in our Pittsburgh office warn: failure to fully define business objectives and key success factors of partners will ultimately lead to additional cost and limited adoption. This can lead to painful transitions from existing APIs to new ones, which will require partners to undertake additional work, further compounding the problem.

Often, when building an API, developers will take the easy way out and expose the messy internals of legacy systems which may have hard coded work arounds and overly complex business logic instead of taking the time to fully abstract this from their new users. APIs developed in this way are very confusing to developers and will, again, ultimately lead to a low adoption rate. Developers need a well documented design that is easy to understand and use. If nothing else remember this from Pittsburgh’s IT consulting experts: developers shouldn’t need to understand your legacy data to use your API.

APIs are designed to extend the capabilities of your platform, while abstracting the oddities of your business processes from your users. Focusing on a user centric design, and understanding key success factors has led the IT consulting team at Pittsburgh’s Savvior to a high rate of adoption.

Best Practices of Good API Design

So we know what can go wrong when developers start to get their hands on an API. Now, the IT consulting experts at Pittsburgh Savvior want you to know what a good API looks like. When done correctly an API should and will:

• Abstract internal systems

  • ?A successful API is easy to understand and adopt. A well designed API turns your service into a platform that developers can grow and expand in unforeseen ways to the benefit of all.

• Increase productivity

  • ?Both clients and internal users won’t adopt the API if it does not increase efficiency in achieving their goals. If the API creates a better-defined, more consistent approach for developing then it will increase adoption.

• Optimize for use cases

  • ?Up front planning around use cases will result in an API which can be developed to tackle critical tasks very efficiently. The design approach should be user centric and not system centric. We should start by considering the problems that need to be solved and the most efficient way to solve them, not with the constraints of legacy systems, which will result in a poor experience.

• Simplify access

  • ?The system is built for and centered around the developers. Opening up communities and giving developers ways to collaborate and showcase their work can be a critical aspect of API adoption.

Technical Design Considerations

Generally speaking, the IT consulting experts at Savvior’s Pittsburgh office recommend using RESTful design for your APIs. (In some cases, however, the IT consulting experts in Pittsburgh have found that formats such as EDI and XML can be used to create the perfect API.)

The concept of REST is to separate API structure into logical elements. These elements use HTTP protocols of GET, DELETE, POST, and PUT to operate.

These are some best practices which should be adhered to in good API design from the IT consulting experts at Savvior’s Pittsburgh office.

• Use nows for endpoints.

  • For example, deleting a book should use the DELETE http resource and the noun ?cars. ?Nouns should always be plural.

• Get? parameters should perform no write operations.

  • PUT, POST, DELETE should be used.

• Sub-Resources should be used for relations

  • For example, GET /cars/22/parts/ returns a list of parts for car 22

• HATEOAS

  • Hypermedia as the Engine of Application State is a principle whereby hypertext links are used to create navigation within the API

• Provide sortable and filterable collections

• Allow collections to be limited

  • The API should always be capable of delivering the minimal payload to the developer

• API Versioning

  • API version should be a mandatory attribute

• Error handling should use HTTP Status codes

• Support X-HTTP-Method-Override for proxy support

API Security

A properly designed API should provide enhanced security for any organization by shielding your legacy and internal systems from any sort of direct access and ensuring data going in and out meets all business rules. The IT consulting experts at Savvior’s Pittsburgh office recommend these best security practices.

• Do not divulge security clues.

  • For example in an invalid username scenario return a more generic response such as “Invalid username/password combination” so as not to tip off the user as to which part of the request was invalid.

• Authentication should use a multi-factor type where two or more pieces of evidence are used to determine the requestor.

  • For example the Oauth2 protocol requires creation of an external token and a key.

• End to end encryption

• Throttling and resource quotas

• Validation of user input

  • Any input strings or objects should never be trusted. They should be validated against specific criteria

• APIs should be RESTful

  • Whitelisting of available HTTP methods.

• Auditing and logging

• No reporting of programing language errors to output

  • These should all go to logs, and a standard error message should be present in the case of a terminal programming error.

Savvior and API design

The IT consulting experts at Pittsburgh’s Savvior have extensive experience connecting to legacy systems to

• Aid in data warehousing initiatives

• Develop and maintain APIs

• Automate Business Processes

• Normalize and De-duplicate data

• Implement Business Intelligence solutions

At the core of any successful software design initiative is proper abstraction and modularity. Designing and maintaining an API is often at the core of this design principle. We allow businesses to

• Increase development efficiency by allowing for rapid development through the use of highly modular assets

• Increase the value of existing legacy systems by creating simple interfaces to often obtuse and complicated legacy workflows

• Make data-driven decisions through business intelligence and data warehousing

• Create eco-systems by extension of business platforms to developer communities

• Protect internal systems from security threats through use of API security measures and isolation of legacy access from internal and external developers