working with new APIs

[David Schwartz 426]

I'm interested in working with an API that has several language bindings available,  but of course nothing for Delphi specifically. (Plaid dot com)

 

Their examples use curl to communicate with their services.

 

What's the best way to approach working with new APIs like this? Do you just use curl? Or build a simple REST client with json?

 

If they have a swagger spec / endpoint available (if that's the right term), can that be used to create something?

 

It seems like it should be possible to translate a swagger spec into virtually any language API you'd want, but this seems to not be what anybody uses swagger for in the Delphi world. I've found several for C#, for example,  but none for Delphi, even though there are plenty of Delphi apps that process swagger for other purposes.

 

I'm curious how others approach working with new APIs?
 

[Remy Lebeau 1393]

35 minutes ago, David Schwartz said:

What's the best way to approach working with new APIs like this? Do you just use curl? Or build a simple REST client with json?

You could use the library version of curl, libcurl, directly in your code.  There is a Delphi language binding available for it.  Or, you could simply convert the curl examples to equivalent HTTP/REST commands and then use whatever HTTP/REST client you want (ICS, Indy, TRESTClient, etc).

35 minutes ago, David Schwartz said:

If they have a swagger spec / endpoint available (if that's the right term), can that be used to create something?

Swagger is just a user-friendly HTML frontend for invoking REST commands.  Any REST command the user can invoke on a Swagger page, an HTTP/REST client can also perform in code.

35 minutes ago, David Schwartz said:

It seems like it should be possible to translate a swagger spec into virtually any language API you'd want, but this seems to not be what anybody uses swagger for in the Delphi world.

Swagger is primarily meant for humans to use, not programs.

[Uwe Raabe 2057]

3 hours ago, Remy Lebeau said:

Swagger is primarily meant for humans to use, not programs.

Well, at least there is Swagger Codegen

[David Schwartz 426]

47 minutes ago, Uwe Raabe said:

Well, at least there is Swagger Codegen

I guess you missed this:

 

 "I've found several for C#, for example,  but none for Delphi, even though there are plenty of Delphi apps that process swagger for other purposes."

 

It does not have support for Delphi.

 

BTW, I posted something related to this a few months back and it garnered a bit of interest, including a recent post about someone trying to solve it. Still, I'm not aware of a single tool that takes more than a limited swagger spec and generates Delphi code that lets you program against the API.

[David Schwartz 426]

3 hours ago, Remy Lebeau said:

Swagger is primarily meant for humans to use, not programs.

There are plenty of tools that reverse engineer SQL -- which is meant for humans to read -- and generate Delphi code to manipulate their underlying tables. 

XML was also meant to be read by humans. XML files are supposed to have a DDL part that identifies the meta-structure of the data so tools can know how to read the tags, but not many do. Nonetheless, XML has become a lingua franca of a large portion of data transfer packets between automated services ... stuff that humans rarely if ever see, let alone read.

 

There was a move afoot at one point to add a similar DDL to JSON specs that allow tools to figure out how to deal with arbitrary JSON data they get, but nothing much ever came of it AFAIK.

 

Swagger is the closest thing I know of to a DDL that describes how APIs are structured, next to design documents (which are often inaccurate and incomplete). 

 

The nice thing about swagger specs is they tend to be generated by the interfaces themselves, rather than humans who do a poor job at keeping specs up-to-date with the actual interfaces. So you know they're accurate and complete at the time they're generated.

 

There are plenty of tools that read swagger and generate binding libraries in different languages that let you program against them quickly. (See the above reference to Swagger CodGen.) Microsoft even publishes several tools that read swagger specs and generate .NET classes in C# to help developers get up to speed quickly with new APIs.

 

So one might conclude from this widespread use of swagger to generate language bindings for their associated APIs that it's a fairly common thing.

 

Just not in the Delphi world -- I guess Delphi folk don't like newfangled tools that generate code for them, but prefer to roll-their-own instead?

 

[Uwe Raabe 2057]

8 hours ago, David Schwartz said:

I guess you missed this:

No, it was just a reply to the quoted statement.