RESTful API Design Essentials That All SOA Developers Should Know

APIs are the foundation of a Digital Business, but how to amass just the right APIs in critical mass?  Here are 11 bits of advice to help your company transform your IT staff’s SOA experts into API superstars.  Our thanks for this thoughtful list of API tips from Laura Heritage, director of API strategy at Akana.

Tags: Akana, API, CRUD, developers, management, model, principals, RAML, REST, security, services, SOA, SOAP, Swagger,

Laura Heritage
Director of API Strategy

"Modeling an API layer is an art form. Start designing your APIs from the top down especially when you are coming from a SOA background."

APIs are the foundation of a Digital Business.  Large enterprises that have extensive skills in SOA and SOAP services development must now expose their core services capabilities as consumable APIs. 


Here are 11 bits of advice to help you move from being a SOAP developer to a RESTful API designer.


  1. SOAP operations will not directly turn into RESTful resources

    A soap operation does not equal a REST resource. I see this way too often when enterprises are trying to quickly get a REST API out the door. Below I illustrate the wrong way and then the correct way to represent the SOAP operation getAllAccounts() as a RESTful resource:

    • WRONG:  /v1/getAllAccounts
    • CORRECT:  /v1/accounts
  2. You may need to call several SOAP operations in order to build a resource.


  3. Don’t expose your backend mess
  4. Do not directly expose the complexities of your information systems.  Establish an API Layer with a well defined resource model that interfaces with the backend applications and their data models.  Modeling an API layer is an art form because setting the scope, grandulatity, and linkages of resources is a negotiation between how a consumer will use the API and theoretical correctness of the model.


  5. Start from top down
  6. Start designing your APIs from the top down especially when you are coming from a SOA background.  This will help ensure you do not fall into the trap of directly modeling SOAP operations as RESTful resources.   It will require you to take a step back and think about your API Layer and what you are really trying to achieve.   As I stated above, resource modeling is really an art form.   In the end, your API design process will be from the top down and a little from the bottom up as you learn.


  7. Leverage these basic RESTful principles
    1. There should only be 2 URIs per resource
      • Listing (collection) - /v1/accounts
      • Detail - /v2/accounts/{id}
    2. Use nouns instead of verbs to name resources
      • WRONG: /v1/getAllAccounts
      • CORRECT: /v1/accounts
    3. Use the HTTP actions GET, PUT, POST, DELETE, and PATCH to perform your CRUD operations on your resources.
    4. GET methods and query parameters should not alter state
    5. Prefer plurals over singulars:  /accounts over /account
    6. Lower case over camel case:
      • Lower case            /accounts
      • Camel case            /Accounts
    7. Link resources accordingly: /resource/{id}/resourceIn
      • Example to receive invoices for a particular account:  /accounts/1234/invoices
  8. Embed or linked resources

    Resource relationships are really a part of the art of resource modeling. The question you must always contemplate; Do we embed the resource or link it?  Here are general guidelines on whether to embed a resource or not:

    • If a resource can live independently then do not embed.
    • If it can not live independently then embed.
  9. Keep complexity behind the “?”

    It just makes sense.  I don’t know one person that likes to deal with complexity before the “?”.

    • DO:                 /accounts?type=corporate&country=US&name=olson
    • DON’T:           /accounts(type=corporate,country=US)?name=olson
  10. Pagination basics

    The common practice for pagination is leveraging limit and offset query parameters as follows:

    • /accounts?limit=25&offset=50
  11. You should send total entries back to user in for example a custom HTTP header: X-Total-Count.   Additionally, provide links to the next or pervious pages again in a customer HTTP header: Link


  12. Use at least these status codes 

    Status code provide important information to the developer on how to interact with your API. These http codes can be used by the client application to programmatically make decisions.  The http codes ensures that your API gives the best experience to the developer as possible so that the developer can create a great client application experience for end user.  Without proper status codes, you will quickly lose favor with the developer community and the end users your are trying to reach.  Please use at least these status codes.


    200 – OK - Everything worked
    201 – CREATED - Resource created
    400 – Bad Request - The application did something wrong
    401 – UNAUTHORIZED - You are not authorized
    403 – FORBIDDEN  - Forget it, you are forbidden
    405 – METHOD NOT ALLOWED  -  Nope don’t even try
    500 – Internal Server Error - The API did something wrong


    Besides sending the HTTP Code, it is helpful and very much appreciated if you send a human digestible message along with the code and possibly a link to documentation to help your developer out. 


  14. Some tricks if it doesn’t easily fit in the CRUD model

    Sometimes the actions you want to model might not fit easily into the RESTful CRUD model.  Notice I said fit easily.  A few years ago I found a blog on it with these common tricks that I have been using. 

    • Restructure the action to appear like a field on a resource

      This works if the action doesn’t take parameters.  For example, the activation action could be mapped to a Boolean activated field and updated via PATCH to the resource.

    • Treat like a sub-resource with RESTful principles

      If an action takes parameters or is more complex, you can treat it like a sub-resource. For example, GitHub’s API lets you star a gist with

      • PUT /gist/{id}/star                  - Star a gist
      • DELETE /gist/{id}/start         - Unstar a gist
    • Sometimes you really have no way to map the action to a sensible RESTful structure

      The most common use case where you will run into this is searching across multiple resources.   In this case, /search would make the most sense.

    Integration & Web APIs
    Enterprise-Grade Integration Across Cloud and On-Premise
    June 23
    Online Conference


  16. Leverage an API Management solution to secure and monitor your API
  17. Look security and management is tough.  The last thing you want to do is code security into the API or build your own gateway.  There is just way too much to think about, security standards are complex, and the threats you need to protect against change rapidly.  You don’t want to be in the business of maintaining a gateway, you should focus on your core value API designs.


  18. Provide an API Description Language document
  19. Great, you have an API design.  Now you need to develop the API and drive adoption of that API.  Providing an API Description Language (API DL) document such as OpenAPI/Swagger, RAML, WSDL, or WADL will help greatly in both scenarios as there are several server side and client side code generators available.   In addition, having an API DL will make managing the API in the API management solution easier, if you didn’t leverage the API management solution’s API designer to design your API.



Laura Heritage is Director of API Strategy at Akana. In this role, she works with customer to establish API strategies and implement API platforms.  Follow  Laura on Twitter at @heritagelaura or on LinkedIn at