API Development

[SDowd]

Hey everyone,
I wasnt really sure if this was the correct forum to post to, so if I am wrong I can post it elsewhere.
I have a potential contract coming up and from my understanding the client would like to create a new C++-based API, based on some existing technologies. Aside from the existing technologies this API will be its own brand new code set. Now aside from general design aspects of inheritence and accessibilty etc., what are some of the challenges and pit falls I can expect to run into. Usually projects I work on are just applications using some form-design tool and linking backend functionality. Designing aspects of an API is a task I've not really had to conquer.
Any ideas or suggestions or just some overall advice would be greatly appreciated.
Again, apologies if this was the wrong forum to post to.

 

[cpjust]

Will you have several different groups using the API?
If so, they'll undoubtedly start to ask for certain features to be added. Some features might be useful for everyone and some might only be useful for 1 group. You'll have to prioritize requests and possibly deny some requests due to time or because it's too specialized...
You'll have to be very careful about making changes to the API because it could break a lot of applications that use it. Backward compatibility is very important.
Only use primitive data types for the public API, otherwise you could run into ABI problems.

 

[SDowd]

Yes, there will be several groups using this API upon completetion. I don't see this API being put on the market until at least 2 years from now. Also, I know this is hard to figure due to scope, but what is a reasonable time to expect to have a rough first version completed? I was thinking at least 2 years, but I really am just shootin' in the dark with that one.
So with maintaining bakwards compatability, would it be a
good idea to just use polymophism, like windows does? I know before they made the switch from 2000 to ME/XP they had something like 14 different functions for a lot of things that all did about the same thing but with different signatures. Would that be the best approach? Seems like it would be a bit bloated when it comes to something like that, but I can't think of any other options...

Only use primitive data types for the public API, otherwise you could run into ABI problems.

would creating a type definition file help, or would that only be for my internal programming? for instance:

typedef unsigned int UINT

I would guess that would only work for my internal programming..?

thanks for your reply cpjust.

 

[cpjust]

Without knowing what the API is, it would be hard to say how long it would take. Could be a few weeks or a few years depending on how big it is.
Using typedefs of primitive types is fine, just don't pass around STL objects and expect them to have the same ABI across different modules.
See: Chapter 63. Use sufficiently portable types in a module's interface

BTW, I would highly recommend buying "C++ Coding Standards: 101 Rules, Guidelines, and Best Practices" and reading the whole thing. It's full of all kinds of useful tips like that.