SitePoint Sponsor

User Tag List

Results 1 to 18 of 18
  1. #1
    SitePoint Addict
    Join Date
    Jan 2003
    Location
    Toronto
    Posts
    234
    Mentioned
    0 Post(s)
    Tagged
    0 Thread(s)

    API Writing Best Practices?

    Hey gang,

    I'm looking for some resources on writing APIs. Google only really brings up actual APIs - I can't find any good sources for writing tips, best practices, etc.

    Any resources you might know of, or tips would be awesome.

    Cheers,
    Adam

  2. #2
    eschew sesquipedalians silver trophy sweatje's Avatar
    Join Date
    Jun 2003
    Location
    Iowa, USA
    Posts
    3,749
    Mentioned
    0 Post(s)
    Tagged
    0 Thread(s)
    Use TDD (Test Driven Development) to guide your design. Use Mock Objects to create fake implementations of dependant objects until you flesh out the API. This will tend promote losely coupled, highly cohesive designs.

    With extensive test coverage, you can the Refactor freely, promoting the DRY Principal.

    HTH
    Jason Sweat ZCE - jsweat_php@yahoo.com
    Book: PHP Patterns
    Good Stuff: SimpleTest PHPUnit FireFox ADOdb YUI
    Detestable (adjective): software that isn't testable.

  3. #3
    Non-Member
    Join Date
    Jan 2003
    Posts
    5,748
    Mentioned
    0 Post(s)
    Tagged
    0 Thread(s)
    All valid points. But I'd add that Interfaces if your using PHP5 (if not, why not huh?) have an important factor in how you implement your design. If a design doesn't feel right you through out the Interface and not much else

  4. #4
    ********* Victim lastcraft's Avatar
    Join Date
    Apr 2003
    Location
    London
    Posts
    2,423
    Mentioned
    2 Post(s)
    Tagged
    0 Thread(s)
    Hi...

    Quote Originally Posted by thody
    I'm looking for some resources on writing APIs. Google only really brings up actual APIs - I can't find any good sources for writing tips, best practices, etc.
    Do you mean designing good method definitions? Do you mean the design of the underlying architecture? Do you mean choice of transport protocol? Choice of library? Do you mean system/server architecture?

    I can probably help if you narrow it down. I've written a couple by now.

    yours, Marcus
    Marcus Baker
    Testing: SimpleTest, Cgreen, Fakemail
    Other: Phemto dependency injector
    Books: PHP in Action, 97 things

  5. #5
    SitePoint Guru OfficeOfTheLaw's Avatar
    Join Date
    Apr 2004
    Location
    Quincy
    Posts
    636
    Mentioned
    0 Post(s)
    Tagged
    0 Thread(s)
    Best tip I could give is making your API solid. Do not make any assumption whatsoever about the end user. It makes me furious when I see an "API" that does html formatting inline without giveing the user an option not to.

    James Carr, Software Engineer


    assertEquals(newXPJob, you.ask(officeOfTheLaw));

  6. #6
    SitePoint Guru Galo's Avatar
    Join Date
    May 2005
    Location
    Holland!
    Posts
    852
    Mentioned
    0 Post(s)
    Tagged
    0 Thread(s)
    Quote Originally Posted by lastcraft
    Hi...



    Do you mean designing good method definitions? Do you mean the design of the underlying architecture? Do you mean choice of transport protocol? Choice of library? Do you mean system/server architecture?

    I can probably help if you narrow it down. I've written a couple by now.

    yours, Marcus
    I think that's exactly what his problem is does not know how or where to start.

    1. Did you made specifications and requirements
    2. Write EVERYTHING your app is gonna do down in an abstract matter.
    3. TDD is next up
    4. Coding alias finger exercise...
    5. Testing and Debugging
    6. Refactor

    Where is this API going for, what fields is it used in, how will it communicate with the EU etc... al thing you need to define before you can even start.

    I would start out with a concept which you already have i presume, then i would make a logbook for the project and use it as your PA, everything from debug-notes to coding idea's you can write down here.

    DO NOT TYPE THIS STUFF OUT, specialist have determined that when you write down words you are actually storing that in your brain much faster then when you type, this is why i dont use elecktronic logbooks but just plain pen and paper, and trust me it works

    Read more and more about how to determine the problems you are gonna have in your app when the requirements and specifications are done, look for exsisting patterns to solve these problems and use self-created patterns where needed.

    Just a few tips hope they help,
    Galo
    Business as usual is off the menu folks, ...

  7. #7
    ********* Victim lastcraft's Avatar
    Join Date
    Apr 2003
    Location
    London
    Posts
    2,423
    Mentioned
    2 Post(s)
    Tagged
    0 Thread(s)
    Hi.

    I think he means APIs like te Amazon API rather than a class library. Not sure 'til we get a reply though.

    yours, Marcus
    Marcus Baker
    Testing: SimpleTest, Cgreen, Fakemail
    Other: Phemto dependency injector
    Books: PHP in Action, 97 things

  8. #8
    SitePoint Addict
    Join Date
    Jan 2003
    Location
    Toronto
    Posts
    234
    Mentioned
    0 Post(s)
    Tagged
    0 Thread(s)
    Hey guys, thanks for the tips so far.

    Basically I would call myself an "advanced" level developer, but this is the first time I have the opportunity to write something that will be utilized by a wide array of people, so obviously I want to be extra careful about sticking to protocol, and writing great documentation.

    The best link I've found so far is http://www.phppatterns.com/index.php...leview/31/1/1/

    I guess what I'm really looking for are tips on architecture, considerations that might not be obvious to a first time developer, pitfalls to avoid, etc.

  9. #9
    Non-Member
    Join Date
    Jan 2003
    Posts
    5,748
    Mentioned
    0 Post(s)
    Tagged
    0 Thread(s)
    www.agiledata.org may shed some light for you in respect to agile development? Also try, dare I say it...

    http://msdn.microsoft.com/practices/ but tread carefully Finally I was browsing through this earlier today,

    http://www-2.cs.cmu.edu/afs/cs/proje...o_softarch.pdf

  10. #10
    Resident Java Hater
    Join Date
    Jul 2004
    Location
    Gerodieville Central, UK
    Posts
    446
    Mentioned
    0 Post(s)
    Tagged
    0 Thread(s)
    To me it sounds like your problem lies in the specifation of things. If you are able to narrow down what you are doing, then ask your self what is this API for. You probably want to write this API along side with a project or two that will be using this API. This will then narrow things down so you have some sort of specification to work to. It will give a good idea how the API will be used so you have some specification. The problem with API's is if you dont do this, or do any TDD that you end up with something that is overblated and cumbersome to use. That that from me as I've been down that road a few times.

    A goos API should be small and simple and fairly modular in order to make sure it does the task it was designed for without doing lots of other crap that you don't want it to do. If you need to use this is a number of very different projects that have ery different requirements, then you will need to think on a more abstract level of course, and build things up gradually.

    Like Marcus said, you should really outline more about this API so we can give slightly better/specific advice.

  11. #11
    SitePoint Addict
    Join Date
    Jan 2003
    Location
    Toronto
    Posts
    234
    Mentioned
    0 Post(s)
    Tagged
    0 Thread(s)
    MiiJaySung - Possibly, but I'm really more interested in general guidelines for API writing, as opposed to an answer to a specific problem. What I've gotten so far has been really helpful.

  12. #12
    SitePoint Addict
    Join Date
    Jan 2003
    Location
    Toronto
    Posts
    234
    Mentioned
    0 Post(s)
    Tagged
    0 Thread(s)
    Quote Originally Posted by Dr Livingston
    www.agiledata.org may shed some light for you in respect to agile development? Also try, dare I say it...

    http://msdn.microsoft.com/practices/ but tread carefully Finally I was browsing through this earlier today,

    http://www-2.cs.cmu.edu/afs/cs/proje...o_softarch.pdf
    Best practices from Microsoft? Yikes!

  13. #13
    Resident Java Hater
    Join Date
    Jul 2004
    Location
    Gerodieville Central, UK
    Posts
    446
    Mentioned
    0 Post(s)
    Tagged
    0 Thread(s)
    Quote Originally Posted by thody
    MiiJaySung - Possibly, but I'm really more interested in general guidelines for API writing, as opposed to an answer to a specific problem. What I've gotten so far has been really helpful.
    API writing is such a generalised thing, that it's hard to give advice really. As I said the best thing is to make sure that the API is simple and modular so that it doesn't end up being too restricting. TDD does help here, along with writing your API with a project that uses it.

    The other thing you might want to look at is lower level languages like C++ where attempts to write API's are a lot more common. There have been a lot of lessons here which you can learn. Things like avoiding the over use of inheritance or over integrated libraries (*stares midlessly at MFC*). The most succesful API's here start small and grow according to the needs of projects as they come. In C++, Policy based design seems to be a idiom that has grown. You can not make an API that does everything. Look at smart pointers, and memory managers typical textbook example... You can not make smart pointers that work for every application, as there are always trad offs to be made. By using *small* policy orientated classes, you can glue together different behavioral attributes.

    Over integrated API's are bad too, as they become inflexible as you only ten to use a select set of features from an API in a given project

  14. #14
    SitePoint Wizard REMIYA's Avatar
    Join Date
    May 2005
    Posts
    1,351
    Mentioned
    0 Post(s)
    Tagged
    0 Thread(s)
    Depends on how big the API is going to be. Is it starting from scratch or is based on already existing one?

    And looking at how other APIs are constructed, may give you a hint

  15. #15
    SitePoint Addict
    Join Date
    Jan 2003
    Location
    Toronto
    Posts
    234
    Mentioned
    0 Post(s)
    Tagged
    0 Thread(s)
    Starting from scratch, but I'll definitely be borrowing from other APIs here and there. Mostly I'm trying to keep it general because I'll be writing several ...going to be busy.

  16. #16
    SitePoint Wizard REMIYA's Avatar
    Join Date
    May 2005
    Posts
    1,351
    Mentioned
    0 Post(s)
    Tagged
    0 Thread(s)
    Quote Originally Posted by thody
    Starting from scratch, but I'll definitely be borrowing from other APIs here and there. Mostly I'm trying to keep it general because I'll be writing several ...going to be busy.
    Then the Java API is a good API to have a look at. It is very well organized and clearly structured

  17. #17
    throw me a bone ... now bonefry's Avatar
    Join Date
    Nov 2004
    Location
    Romania
    Posts
    848
    Mentioned
    0 Post(s)
    Tagged
    0 Thread(s)
    Although I like Java, I would recomend to look at other dynamic languages like Python because PHP cannot behave like Java.

  18. #18
    get into it! bigduke's Avatar
    Join Date
    May 2004
    Location
    Australia
    Posts
    847
    Mentioned
    0 Post(s)
    Tagged
    0 Thread(s)
    thody:

    You might want to take a look at the book "Web Application Design With PHP 4", it covers this aspect of development quite well.


Bookmarks

Posting Permissions

  • You may not post new threads
  • You may not post replies
  • You may not post attachments
  • You may not edit your posts
  •