So,
I don’t understand what it is about Web Services and web based API, but (coming from a platform developer) ya’ll don’t know how to document the Data Model.
And GitLab is not alone in this one. Yes, whether RESTful or SOAP, how to execute the web service is one thing, but what are the meanings of the data returned?
For example.
I have problem where I need to analyze each project and retrieve the ‘.csproj’ file from each project in order to do an evaluation of that project definition. Thankfully GitLab api to the rescue as it allows me to do that. However, take for example the command: projects/:id/repository/tree
Now, this returns:
[ { "id": "942935235aa41ea3ace395c3d4349b174b53a56d", "name": "Attributes", "type": "tree", "mode": "040000" }, { "id": "1ff0c423042b46cb1d617b81efb715defbe8054d", "name": ".gitattributes", "type": "blob", "mode": "100644" }, ]
Now, most of that is readily understandable. But what is “Mode” I have inferred through inductive reasoning that 040000 somehow could mean “Folder” and 100644 might represents “File”, but most likely they are bitwise attributes? Could there be a file that is 100642? If I hard code direct string matching on those values, the code could fail. There is also the “type” field which appears to have either “tree” or “blob”. That also could be the differentiation of file or folder, but are there any other options. Can “type” have some other value beside tree or blob? These questions are not resolved anywhere in the API documentation.
This is what is called a data model specification, that says:
Here’s the command: /projects/owned
returns:
JSon Array of
Git Project Structure:
id int
Name string
description string
tag_list array of string
public bool
archived bool
etc, etc, etc.
In every search I try, and all the documentation that exists, there is no specification for the data model for the returned structures like this, which makes parsing the data and making sure of complete accuracy is very slim. I can guess a lot of meanings, but my guesses are in no way a valid spec.
Does anyone know where this specification might be found?
Thanks
Jaeden “Sifo Dyas” al’Raec Ruiner
PS GitLab is NOT alone in this failing. The more I migrate into using web services, whether RESTful or SOAP, I am finding more and more a complete lack of data model explanation, so I have posted similar such complaints all over the place.
It would be like Microsoft Posting the Methods for handling the WM_MOUSEDOWN message, but not providing the definition for the message structure.