Method naming convention in SDKs

Question

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(){
    ...
}

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](https://msdn.microsoft.com/en-us/library/ms229002(v=vs.110).aspx) - 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

score 3 · Answer 1 · answered Apr 11 '17 at 18:48

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.

Method naming convention in SDKs

1 Answers1