web services - SOAP API parameter best practice -

i have set of soap webservices tightly coupled application within same architecture need api other applications hook into.

at moment, services use parameter (and method) structure this

entity getentity(int entityid) entity getentitybyname(string entityname) .... etc.

in case of creates use: void createentity(entity entity)

i wondering though better this:

entityresponse getentity(entityrequest requestobj) .....

and in requestobj have id, entityname , depending user supplies, can perform either function.

and create be:

createentityresponse createentity(createentityrequest requestobj).

my thinking doing this, api can change internally...add new parameters etc without breaking integration has been done.

i think there several design principles may want consider:

1) database entity vs data transport object dto

looks entities come directly database mapping? exposing entities api, fancy sql query browser. it's not wrong achieve better de-coupling if expose dto's in api. dto's more future proof entities , more generic.

2) soap vs rest

if want achieve maximum of future proofing might want consider rest. rest specification have more options extend api later. instance if @ apis facebook purely pass in parameters , receive in return key-value map of parameters passed in. generic. in soap end in defining of eventual attributes upfront. need introduce placeholders et cetera. there reason why soap contract protocol , has advantages code generating tools more date , lots more. rest more flexible while loosing of goodies had in soap.

this read: https://www.mulesoft.com/lp/whitepaper/api/secrets-great-api or raml design spec mule powerful tool when comes designing rest apis.