[Web] API, Restful API, Documentation and Best Usage (Thoughts)

Discussion in 'General Webmaster Support' started by rover2341, Sep 3, 2014.

  1. rover2341

    rover2341 Is riding a roller coaster...Wee!

    +114 / 0 / -0
    What Is API, And Restful API

    When I say API, I mean You make a HTTP Request, and a server picks it up and does something. It may return data to you in general as string, json, or xml.

    Restful API: Is close to the same thing, expect it pays attention to the "Method" or "Verb" Sent in the request. GET, POST, PUT, DELETE ...ect
    The Main Benefit of Restful API Is that your apis have standardization on naming, and usage.


    A Project I have more or less finished at work. Has a little over 100 API's.
    And the requirements are tweaked often, so the apis need updated or additional ones are needed.
    This is not Ideal.

    Why So Many API's?

    Lets Assume you have a table called Person with 50 Property's (and they stay the same, no additional)

    Update Person API's:
    There are several different apis that update person.
    but some update a single field, where others update a few and some update several.

    Get Person API's:
    There are several Gets, some that get all (most) the fields, and others that give just some, or even one.
    Now I could reduce this down to 1 or 2. And just give them all the data they are allowed. It wouldn't be the most efficient but it would reduce calls (Id like to avoid this)

    • New Requirement
    • Determine Additional/Change In API
    • (If I was not the person to do the last step) I am given API request.
    • I Create/Update API
    • Test API
    • Create Documentation
    • (If I was not the person to determine api request) Let Person know who needed It
    • They Use it, And If they have no problems we move forward. If not I go back and fix any issues related to the update/new api, and then we go back and forth in till we are done. Often during this process they realize they need additional data in the api.

    For the Table "Person"

    Proposed Process
    • New Requirement (That's it the first and last step)
    Why is this better?
    • No Additional Or Change In API needs be considered
    • I am not given a API Request
    • I am not Creating Or Updating a API
    • I am not testing API a new or updated API
    • I am not creating additional documentation
    • I am not dealing with letting someone know I am done.
    How can this be achieved?

    On Update Person, You send in a list of key value pair, of the property and the value.
    On Get Person, You send in a list of properties you would like.

    Documentation would give you the list of all the properties.
    And For things with "Rights" Requirements ect would be explained in the documentation.

    Other Features
    All Apis would have a optional Token Pram. This is for use of mobile applications, that do not have cookies, or its too much of a pain to get the cookie in the response and inject it into the next message.
    With this, it would check there http request for cookie first, else check token.

    This would make all the API's 100% Access to Phone Apps.

    Also All of the apis would make a function call to Service, where all the logic would exist. This way for applications, that prefer use of Service Or if I want to turn on the service It can be done with extremely minimal effort.

    Also Using Rest It will look in the http request to see if they are requesting it as json or xml.

    By adding in the service layer, Its used as the business layer, (even if the service is never exposed) making it easier to test and maintain the code.

    What Makes a Good API/Service
    • Documentation
    • Testing
    • Ease of use
    • Secure
    • Efficient
    • Work Everywhere
    • Maintainability

    • Why isn't this a common method on medium to larger projects. (that use alot of ajax calls in the html, or in my case aspx)
    • Why haven't I heard of this
    • Why is this idea unwise?
    Please tell me why this idea is unwise.

Share This Page