What term best describes the "mentality" with which an API is designed?

Question

As someone whose mother tongue is not English, I'm sometimes having a hard time having the correct feeling towards the meaning of some words. This is one of those situations.

I'm looking for a term that refers to how an API (an application programming interface) is designed. For example imagine a piece of text with such statements:

• For every *_new function, there is a *_delete function.
• All functions creating shared objects take a name parameter as the first argument.
• All int *error arguments used for returning error code are optional and come last in the argument list.

How do you refer to the text containing these statements? For example, is it the style definition of the API? Are these the conventions of the API?

Answer 1

They are referred to as "Coding standards" in the software engineering world.

Answer 2

You might be looking for design template or design pattern.

Design patterns are not frequently associated with interfaces, but the term does come up, as with the "facade design pattern".

From wikipedia:

A facade is an object that provides a simplified interface to a larger body of code, such as a class library.

Simplification comes from creating reusable and familiar patterns that meet the necessary functional requirements.

You may like to know that "design patterns" is not localized to just software development. It was codified as an architectural concept by Christopher Alexander, and his ideas were published in "The Timeless Way of Building" in 1979. This book is literally about the architecture of buildings and construction, but lays a foundation for applying the concept to other fields of design.

Incidently, while on the subject of architecture, the word archetype, comes to mind as well (although the words are not related directly).

Archetype: the original pattern or model of which all things of the same type are representations or copies

But I don't think you will see "archetype" used as frequently in this case.

Answer 3

if you wanted to describe an implementation as being proper example of a given style you could use "idiomatic".

"That is an idiomatic example of a RESTful archtitecture"

Merriam Webster

1: of, relating to, or conforming to idiom

2: peculiar to a particular group, individual, or style

Answer 4

The list shown 'specifies' a series of realities of the API; ie it is a 'specification'. There is no room for discussion, it states a series of facts about 'specific' things. Specification language is a very standardised and accepted form of English intended to be as clear as possible for the purpose of imparting important information. It is almost an attempt to write computer code in plain English :-) What makes it easy to recognise in a good example is what is missing:
no colloquialisms, first- or second-person modes or humour; no decoration or variety (the same sentence format is factored out and used to achieve the same purpose each time it is needed); no sarcasm, irony or exaggeration (care is taken to minimise assumptions by the reader, e.g. abbreviations are expanded locally or adjacent, punctuation is avoided where possible because misreading it can affect the meaning). The words 'Required' and 'Shall' may be used to give a special authority to some statements.