0

I'm building a client for an API.

The API takes a query param that looks something like this 2-10, that's a range and notice that it uses a hyphen (-).

Usually, data comes from another place using en dash (–) instead of hyphen.

If the api is called using an en dash instead of a hyphen, it will return empty, so we need to convert en dashes to hyphens before sending the request.

I see two options for handling this:

  1. On the API client that I'm building I can get the range and silently replace en dashes with hyphens before doing the request to the API.
  2. Throw an error on the client if it is used with en dashes instead of hyphens and let the code that's going to use the client handle the issue.

Any advice on which way to go is highly appreciate it.

7
  • 2
    Why not provide two separate fields instead of requiring the caller to concatenate the values with a dash?
    – John Wu
    Jun 14 at 2:22
  • 1
    In that case, why not officially accept both? Jun 14 at 2:45
  • 1
    Allow, and document, that ranges may be specified with both em and en dashes. Then it is not an error to be corrected, but valid input. Jun 14 at 2:55
  • 1
    You cannot accept both, because the client is for the API he probably doesn't own. Even if he did, changing the API because of this is a terrible idea, because you let an implementation detail from some unrelated context creep into the implementation of the API.
    – Blaž Mrak
    Jun 14 at 4:11
  • 3
    the values are already concatenated from the perspective of the caller I don't think that is true. The other service is returning concatenated values in a string, true, but it is in a different format, obviously (or we wouldn't be having this conversation). Anyway, it doesn't really matter what the caller has retrieved from some other service. Your API's interface should make sense for itself and not be coupled to some third party.
    – John Wu
    Jun 14 at 5:27
1

The user of an API doesn’t care where the data comes from; there is a contract between the API and the user. If the API uses a different service that makes trouble, the API must either report an error, or a correct result. A silent incorrect result is unacceptable, it means your API is broken.

Now from your description it is less than clear to me what you are actually doing, whether you are creating an API or a client, and who is getting data from another source. If the API is broken you either shout loudly at the API creator to fix it, or live with it. But you should have one method in your client code where a range is specified using a clear and simple rule, and that method turns the range into the format needed by each other method it calls. It might not be hyphen vs dash, it might be a completely different format like “from: 2 to: 10”. Once your method is written it should isolate any callers from these problems.

3

Your question is missing important details, some of which are mentioned in the comments, but the requirements are still muddy.

For example, when you use passive voice in "range is retrieved from another service" you leave unclear who does it, what the other service's API definition is, who could possibly be responsible for interpreting the string as a range.

  • If the user retrieves the range and enters it into your API (copy&paste?) you got a severe usability issue and source of errors, but it could be argued that the user is responsible for fixing the format. As a user, I would refuse to use such software.
  • If your application retrieves that range, it is your responsibility to interpret it according to their API and transform it appropriately before passing on to the other API.
  • If the other service API definition says that they format ranges with a hyphen but their implementation uses an en-dash you need to either request that they fix their implementation or you need to accept the incorrect format in the interest of interoperability. There are a number of examples where this is being done in API clients.
6
  • Your cases 1 and 2 are the same -> he is building a client. User of the client could be his application or someone copy pasting, it doesn't matter. The third case is interesting, but you still won't wait for them to fix their API. You will replace the dash or throw. I do agree, replacing is more usable, but both are correct, no matter the responsibilities.
    – Blaž Mrak
    Jun 14 at 9:03
  • I think the idea to split this answer into 3 bullet points is fine, since there are 3 places where the issue in theory could be handled: the place where the data comes from, the OPs application, and the API where it goes into. However, @BlažMrak has a point: currently, the first two bullet points are - arguably - describing both a scenario where the OPs application must handle the issue.
    – Doc Brown
    Jun 14 at 9:41
  • @DocBrown Even if the other service has the wrong implementation, a half decent design would put that in a separate client/function. The bullet points are not even relevant, because it really doesn't matter from where the dash originates - user input, your app, or another API (all this is basically user input as far as the client is concerned). Main point being, it is just a usability thing. Replacing the dash in client code will make the client less painful to use, but it is also fine to throw, because in the client's context this technically is incorrect input.
    – Blaž Mrak
    Jun 14 at 12:00
  • 1
    Excuse me, but it does matter where the en-dash originates, because to fix the problem you need to understand it. Otherwise you're just putting a patch over a sore wound in the hope it won't cause more trouble. There are cases where there's the only choice because you have no choice, but if there is a cleaner option it is preferable in the interest of understandability and maintainability. Jun 14 at 12:08
  • The client is not aware of the second API or a UI or of any outside application. The client has a function getSth(param: string). What we are discussing is: should this function fail or not fail on not really incorrect input? I say no, because it makes it a pain in the *** to work with as a developer - as you said in the first bullet, you would not use it as a user if it behaved like that. As a developer you are THE user.
    – Blaž Mrak
    Jun 14 at 18:08
-1

You can do whatever you want for the client really, but the client would be more robust and easier to use if it replaced the dash automatically.

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.