Structuring API Functionality (with a Separation of Concerns) A guide as to how you can move forward in your work with doing structuring API functionality.

I don’t have a lot of experience when it comes to creating APIs. I’ve done a fair share of work when it comes to integrating WordPress with third-party APIs, but I’ve spent very little time working on creating a system that has its API with which other systems can interact.

As far as the latter is concerned, I’m actually in the middle of doing that (and I’m learning a lot). The gist of the project is there’s an iOS app that’s interacting with WordPress via the REST API in a bi-directional way.

Structuring API Functionality: The WordPress REST API

I’m eager to share more about it, but I need to do so when the project is further along.

But when it comes to working with third-party APIs and then building components of a WordPress project that interact with them, two of the things I consistently find useful are:

And the last two points above are what I’m looking to cover in this post.

Structuring API Functionality

No code is involved in this post, but perhaps it’ll be a guide as to how you can move forward in your work with doing structuring API functionality or doing something similar in your own.

Third-Party Libraries

I mention this only because I think it’s valuable to re-use tried and true solutions that have been tested (and thus used) across the board in a variety of projects.

Structuring API Functionality: Guzzle

Guzzle is my library of choice. Yes, WordPress has built-in functions for communicating with other URLs, but there’s more you’re able to do with Guzzle (especially as it relates to components of the request) than with WordPress.

Granted, this is my opinion, but I enjoy working with it. And the documentation is solid.

Diagramming the System

When you work with integrating with third-party APIs long enough, you’re to get used to the process of setting up how the system works. Usually, it goes something like this:

  1. create an API client to connect to the API,
  2. set up the functions necessary to make the requests that you need,
  3. parse the response,
  4. return it to the original object or function that invoked the request.

This is a bit of an oversimplification (after all, creating the API client can be a task in and of itself), but the points all remain the same (and may not make for a bad series 🤔).

Anyway, above all else, it never hurts to diagram the system. This is something I still do because it helps me, in a sense, articulate what it is I’m building and see if there are gaps in the flow of control through the application.

Structuring API Functionality: Diagrams

Here’s why, if no other reason, this is important: Articulating what you’re going to do helps you to understand what you are doing and often exposes gaps in your thinking that you take for granted.

So when it comes to laying out a system, don’t assume you’ve got it all figured out.

Separating the Functionality

If you’ve read this blog for any length of time, then you know I’m a fan of following the whole “separation of concerns” development ideas.

This is true for multiple reasons the least of which are not:

  • being able to unit test an API client in isolation,
  • keeping the code for communicating with the front-end and the back-end independent.

When you have a class dedicated to running business logic on the values, you can offload much of the error handling into the intermediate class.

This means that the core class responsible for the majority of the business logic should have exactly what it needs to do its work. This doesn’t mean there isn’t some error checking should be in place (division by zero or something, you know?), but it means that data can be checked before it even gets to the core class via the intermediary class.

And not only can it check for any missing information, but it can also report those errors back to the front-end.

Three Points to Remember

If you’re creating an Ajax-reliant system in WordPress, the point of all of this is three-fold:

  1. diagram the system you’re creating,
  2. create an interstitial class for handling any missing information and report the errors back,
  3. only send the full information to the core business class after all of the information has been verified.

Once you’ve done that, the goal would be to have the core business class returning the requested values without error since they will have been caught before even reaching it.