I have been asked to write the signatures for and API end points GET/POST/PUT methods. I'm having a hard time wrapping my head around what the point of this is. My co-worker asked if I could do this before they come in and add the implementation. Would this mean that all I'm adding to the Web Api controller is a bunch of code that looks like this below?

GetSomething(string value1, string value2)

PutSomething(string value1, string value2)

PostSomething(guid value1, int value2, string value3)

I'm having a hard time understanding what the point of this would be. Since with out having the return types and what not the code isn't usable if they have not been declared. I can see this being useful in documentation though.

  • 1
    Because it defines the external API. Apr 8 '15 at 1:47
  • But should it look like the above and be added to the class or do you normally write the signatures out in documentation .
    – Stavros_S
    Apr 8 '15 at 2:39
  • 1
    Sounds like documentation to me....
    – Eric King
    Apr 8 '15 at 3:40
  • You should ask your co-worker.
    – Rocklan
    Apr 8 '15 at 3:47

The general case here is identifying the external interface.

It should be possible to write an interface for two systems or modules to interact, define what the method signatures are, data formats, preconditions/postconditions, etc. with zero implementation behind it.

Next, separate teams work on separate code that use that interface. Perhaps one team implements the code that makes the interface work while another team implements the code that invokes the interface.

Interfaces can be difficult. Moving data between systems, formats, etc. can be fraught with problems. By identifying interfaces early, documenting them, and having plenty of time to test, you have a better shot at having a fully functioning system by the time it is supposed to be delivered.

In this specific case it might be true that return types or certain other details are not known yet, but enough is known to begin work. It is impossible for anyone here to say for sure given we are not on your team at work. However, I have seen interface development proceed this way in the past. Customer says "we need a web service that adheres to this interface, but we are not quite sure what to return yet. We need customer data, but do not have a list of all the fields yet." That is enough to start on. I have a pretty good idea of what the code behind the interface needs to do, I am just not sure about petty details which can be ironed out later without affecting the schedule.

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.