Hi,
I am looking for unusual data structures in API's that are open to the public.
It's not my intention to shame or flame any API vendors I'm looking for some examples as use-cases for a library I'm building.
For example I once ran into this API structure when there were validation errors:
{
data: null,
errors: {
fieldName: [{
description: "some friendly message",
code: 000
}],
otherFieldName: [/* ... */]
}
}
The challenge here was that the fieldnames aren't an array and we didn't know the fieldnames up front.
In our case we were mapping it to C# so we wrote a custom converter mapping it to a List<FieldValidationError>.
public sealed class FieldValidationError {
public string FieldName { get; set; }
public string Description { get; set; }
public int ErrorCode { get; set; }
}
And this made the error logging a lot more straight forward.
Sadly I don't remember which API this was, and I think it was a closed system anyway.
What I'm looking for in a nutshell:
- A link to Documentation that is open to the public
- A short explanation why it's unusual perhaps with an example from JSON/XML to the eventual model in code you'd wanted it to look like or map it to (can be any language).
Top comments (3)
I stumbled upon this API documentation when starting to work for one of our clients:
bullhorn.github.io/rest-api-docs/
What's pretty unusual is the way how they set up the output of their API. For context, it is possible to create custom fields in the backend of this application. The way this API works is in your search request you can add the "fields" parameter, allowing you to add your custom fields to the response.
You can apply a query to your search path which applies Java Persistance Query Language (JPQL). When I started working with this API I had to look up how exactly JPQL works because this was the first time I've heard about this.
There are some dangers about allowing custom fields to be added though, when I started working with this application, the first thing I noticed was that all the custom fields don't have well thought out names. You'll see stuff like "publicDescription" which will make some sense, but then the next field in the list is "customText3", which is also (unfortunately) incorporated into the code that handles these requests.
To provide an example of the search endpoint how I found it in our project. Please note that I removed a lot of identifying fields. And yes, unfortunately, currently the request is being sent without encoding the URL.
/search/JobOrder?query=isDeleted:0 AND customText3:"yes" AND NOT id:10765&sort=customText4,-dateAdded&count=1&fields=id,customText20,dateAdded,startDate,dateEnd,address=(city,state),submissions=(id),owner=(id,email,phone,mobile,name,occupation,customText1),assignedUsers=(id,email),customDate1
The output shows as following:
dev-to-uploads.s3.amazonaws.com/up...
Hmm that is indeed unusual, I had a quick glance but I can only see weirdness in the query language.
Does it also have exceptional data structures that are being returned or that you have to post perhaps?
Fortunately not, other than the JPQL. Once you get the hang of that, it's peanuts. The results you get is pretty straight-forward with JSON replies. Other than the fact that you have to define in your request which fields you'd like to have returned.