Non dull API

How to create an API for smart? Such an api, so that creating a client for him was not a boring mechanical process, but a real adventure with elements of detective, horror and mysticism? Such api, which users will be excited about telling colleagues? Api brain-blistering, making you laugh, scream and cry? I tried to select the best practices I had to face.

Do so

1. Avoid the obvious names. checkInDate is better written as start_date, even better as sd, even better as d. Then a long and ugly checkInDate / checkOutDate will turn into laconic d1 / d2. More great naming ideas can be found in the book “Perfect Code” in the chapter “The Power of Variable Names”
2. Do not use standards. ISO 8601? To convert the date using standard libraries that are available in any programming language and without writing a regular program? Boredom.
3. Do not use subject terms in the names. Better think of something as abstract as possible.
4. Think up your own system of state designations. For example: 1,2,3 - is, no, under the order. Do not try to write states directly and even more so, never use the reference book of states.
5. Pass the nested structures as a list of flat related via internal IDs generated specifically for this answer.
   

   { Jacket: \[{MaterialsIds=”m1,m2”, Pockets: “p1”, Price: 12000}\], Materials: \[{Name: “Stormscale”, Color: “Tear of Elune”, InnerId=”m1”}, {Name: “Feather of Valor”, Color: “unpredictable”, InnerId=”m2”}\], Pockets:\[{Type: “Invisible”, Contents: “Soap”, InnerId="p1"}\]} } 

6. Do not repeat.

   
   

   a. Think of different systems to indicate the states of different objects. You can add color to the digital one described above: green, red, yellow.

   
   

   b. Change not only the data format, but also the format for recording field names - srart_date: 25/12/05, endDay: 2012.11.23.

   
   

   c. Do not forget about a huge selection of delimiters: comma, dot, semicolon. Add something non-standard to it - a percent sign or a grid.

   
   

   j. The list goes on, be creative.

   
   
7. Replace True / False with 1/0, and even better with 0/1. Turning a simple “has_goods: True” into four questions - a student? quantity? just 'yes'? or, “no”?
8. Use bit flags. So you will demonstrate your exceptional education. Translate them into decimal form for less obviousness. Do not pass the mask along with the flags, or even in a separate dictionary. “Flgs: 16” in the structure and a list of flags in the documentation is an excellent option.
9. Try to shove as many meanings as possible into each field.
   

    has_goods    [-2, -1, 0,   ],  : [,   ,   ,    ] 

10. Add a required parameter to the query, which can have only one value.

    
    
11. Add a parameter to the request, the meaning of which will change depending on the value of another, optional, parameter.
    

     http://example.com/myService?cloth_type=silk&and_better=1  "cloth_type" -     (, ,    ,     ,     ),  "and_better"       .  “ ”    "and_better"   (-1, 0, false, not)     "and_worst"   ,   /,     ,     - . 

12. Set the ranges on the enumerated data by a sequential list, and on the data, the order of which is defined only in your application, the beginning and end of the range, and even better through a hyphen or another separator to taste.
    

     http://example.com/myService?d=11.12.05&d=12.12.05&d=13.12.05&colors=green;yellow 

13. Use the same type names for fields with different data types.
    

     http://example.com/myService?cats=5&dogs=4&hamsters=0  cats  dogs    ,  hamsters    . 

14. Do not handle errors. Are incompatible parameters passed? An empty response should be a sufficient hint. Or lack of response. Or send an event generated by your application.

15. No documentation needed.

    
    

    a. If you had to document, skip the most “obvious” places.

    
    

    b. Do not complicate the documentation with examples.

    
    

    c. Document the missing functionality, which you will definitely add later.

    
    

    d. Divide the documentation into several parts and give each one only to those users who guess to ask about it.

    
    

This list is based on real events, the names are changed in the interests of confidentiality, all matches are not accidental.

PS Write about your heroes and their epic acts in the comments.