2

I create my API and now I generate SDKs for my users access them. Swagger generates a ugly name, e.g:

public void sellersSellerIdShipmentPost(){
...
}

Of course it's difficult to read and understand. What's the method naming convention for SDKs? In Facebook API, they use somenthing like CreateAppGroupDialog but seems like a SOAP and not API.

What's good practice for SDKs? I don't know but I think that maybe a good ideia is use httpMethodName. E.g:

public void putSellersShipment(){
    ...
}
public void postSellerShipment(){
    ...
}

closed as primarily opinion-based by gnat, Kilian Foth, Thomas Owens Apr 13 '17 at 13:14

Many good questions generate some degree of opinion based on expert experience, but answers to this question will tend to be almost entirely based on opinions, rather than facts, references, or specific expertise. If this question can be reworded to fit the rules in the help center, please edit the question.

  • 1
    Naming is hard. I know you're using Java, but having a nice set of guidelines and following them is a good practice. So, for starters, I'll leave this here: Framework Design Guidelines - Naming Guidelines - It's from Microsoft, and the book tells several things they did right and wrong on the .Net Framework. Given the (good) quality of the framework, I think it's worth reading. – Machado Apr 11 '17 at 18:50
3

There is nothing particular in SDKs. You name things in a way which makes them explicit and unambiguous. Your CreateAppGroupDialog is a good example.

By sticking with HTTP verbs, you introduce two potential issues:

  • The interface becomes leaky. As a user of your interface, I don't care it uses HTTP under the hood, and I especially don't care about the semantic difference between PUT and POST. If I want to create an application group dialog, I don't need to figure out whether I should PUT it or PATCH it, or whatever the HTTP spec says about the appropriate verb.

    Ideally, it shouldn't look like SOAP, nor like REST. It should look like an interface, and nothing more. Protocols are implementation, and you should be able to swap them without any change of the interface.

  • There may not be proper verbs to express what the method is actually doing. If your business logic has a place for a method called SqueezeJuice, you name it just like that; the fact that HTTP specification doesn't have any SQUEEZE verb in it is irrelevant.

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