0

I have a hard time trying to find a 'rule of thumb' to follow when dictating certain responsibilities to either the API, or the client-side code base.

For instance, if I know a dataset should be returned in alphabetic order, should I as a front-end developer expect the data to be properly ordered alphabetically by the API designers/developers, or should I expect to be the one to order the data.

Extending this thought, what are ways I can determine if data-related operations are the front-end developer's responsibility or the api designer/developer's responsibility? I want to know when to draw the line and expect things to be done before it reaches my jurisdiction.

3

All interfaces should have clear "contracts" that specify what each side can expect from the other side. If it's stated in the contract that data is sorted, you should rely on that. If it turns out that the service delivers unsorted data, you can blame it :-)

If you're unsure about some part, that's normally a sign that the contract isn't written properly. Depending on how much influence you have on the API's author, you should ask them to clarify, or if that is not possible, assume the worst and program defensively. In this case it would mean that even if your tests indicate that the service returns sorted data, assume that it's just lucky chance and sort anyway.

6
  • I usually call that endpoints "hostile endpoints" or "hostile systems". Assume they'll do anything possible and program defensively against them. Specially true if I'm working with code created by another team which is not interested in solving your problem, but you need their code/API anyway.
    – Machado
    Jun 7 '18 at 15:33
  • Do these contracts manifest themselves as tests? What is a common representation of these contracts with web apps? Jun 7 '18 at 16:34
  • 1
    First and foremost API documentation, as DFord writes. It should precisely document the properties of the interface, not just be a copy of the requirements docs. If some field should contain a date, the docs must specify format and possible exceptions (may it contain a NULL value? What are minimum and maximum values? Is a time included? If yes, does it indicate the timezone?) Tests are a welcome bonus, of course. Jun 7 '18 at 16:57
  • @Hans-MartinMosner I am curious as to why you used the term contracts instead of just saying 'documentation'. Is the term 'contracts' more representative of a fundamental software principle? Not trying to knock you, I was just completely unaware of the term me being a newbie and all. Jun 7 '18 at 19:07
  • I'm sometimes under the impression that for certain developers the actual behavior of the software takes precedence over the documented behavior. By stressing that the documentation is a "binding contract" it is far easier to determine who needs to fix something if there is a problem at the interface. This is not a matter of pointing fingers but of avoiding endless discussions and technical debt in workarounds for interface specification shortcomings. Jun 7 '18 at 22:46
1

You should start with the API documentation. If the documentation says that data is going to be returned in a certain way, then it should not be the client side code's responsibility to sort the data or to manipulate in the same way. It could also lead to wasted effort.

If the documentation does not specify, then you should assume that it is not being done and either check on your end or just do the manipulation.

Essentially, the line is drawn with the documentation. If the manipulation you need done is not in the documentation, then you should assume it is not done. If there is no documentation, I would assume the manipulation is not done. You might be able to guess from the API endpoint name, but that is still an assumption on your part.

0

You say “in alphabetical order”. I say that ordering is locale dependent, and different clients will want different ordering. So that particular thing should be left to the client.

Many clients allow ordering in different ways, like address book sorted by last name, first name, company, ascending, descending. If the client changes the ordering, it shouldn’t have to request the data all over again.

And your clients combined have much more processing power than the server. So the only case where I recommend server processing is filtering when it significantly reduces the amount of data transferred.

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.