Help Designing An API

[DOOMReboot]

Would anyone be willing to help me design an API using modern C++ techniques to load and display data from the original DOOM game's data file (WAD)?

I've got a fair amount of C++ experience and have already written the full library to load DOOM's data and run an approximation of the original game. It uses just C++ and OpenGL (through SDL2).

However, I did not have much API design experience when I started and finished (and it Shows!). I'd very, very much like that to change.

With your help and guidance, I'd like to rewrite the entire library (it's HUGE!) with proper, modern C++ API design in mind for two reasons:

-To help others learn more about how DOOM, and well-designed public C++ APIs, work
-To a lesser extent, have an API library that I can open source and be proud of

If you've any experience designing APIs or even SDKs and are willing to lend a couple hours' worth of time, please let me know.

Here's a bunch of media related to the first iteration of the DOOMReboot project (It's real, I'm not just having a laugh):

https://twitter.com/DOOMReboot/media

[thmm]

Maybe listen to the thoughts of an expert.

C++Now 2018: Titus Winters “Modern C++ API Design: From Rvalue-References to Type Design”
https://www.youtube.com/watch?v=2UmDvg5xv1U

[kigar64551]

Most important, think of the header file as the "public interface" of your library. Anything that does not have to be public, should be considered "private" (internal detail) and therefore should not be in the "public" header file! I have seen way too many libraries that have cluttered their "public" header file(s) with internal constants and other implementation details... which not only clutters the namespace of the caller with tons of unneeded symbols (risk of name conflicts!), but also hinders the future development of the library...

[seeplus]

For a book on API design, consider:

Martin Reddy - API Design for C++
https://www.amazon.co.uk/API-Design-C-Martin-Reddy/dp/0123850037/ref=sr_1_3

[kbw]

Rather than your interface being stateful have you considered a stateless api with unique keys.

Also, it might be handy to support different data types that have distinct identifiers, kinda like a mime-type.

Nothing is built as finally intended to begin with, the final intention isn't known. Instead embrace build things iteratively, new versions, new branches of ideas, ... experiment and have fun.

EDIT:
Why do would someone do that, rather than the simple direct ways shown so far?
* You can put your code in a library
* That library can expose a simple C style interface, which makes it compatible with almost any language.
* That library can be a client for a remote server implementation, making it globally available.
* As an example, consider Redis.

[jonnin]

consistency. If its like the standard library (eg, you expose a container) then follow the c++ pattern. But whatever you do the names of the objects and methods should be consistent to the point that a user can guess a name after playing around for a few min and have a good chance of getting it right, and parameters should be in the same order for similar functions, and same numbers and types.

In my opinion that is more critical than a goof like exposing a private container by accident or the like. The user can debug that, and looking at the consistent interface, see that you probably didn't mean to expose it (its not documented anywhere, and nothing else like it anywhere, etc) but nothing sends it to the recycle bin faster than having some functions with _ and some with mixed case and so on where it is impossible to remember or guess anything by a pattern.