I'm about to set up an AWS API Gateway via Cloudformation and wondering what is the better solution:
should I use the AWS Resources for Resource and Methods or is the better approach to import the well known OpenAPI (Swagger) file we have into the API Gateway Resource?
From my researches I found out that Using swagger has some limitations (https://docs.aws.amazon.com/apigateway/latest/developerguide/api-gateway-known-issues.html) but on the other hand its kind of the standard to create APIs.
So going full in on AWS Cloudformation might have some disadvantages I cannot see right now. Thats why I'm asking for experiences from someone who was in the same situation. Grateful for any guidance...
Merci A
Personally I find the best way to develop api gateway resources is using the Serverless Framework its super easy to use and integrates very easily with other AWS services i.e. Lambda.
Also under the hood serverless is just cloudformation templates so its very flexible.
Nowadays you can write your templates using SAM (Serverless Application Model https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/what-is-sam.html) if you don't like the serverless framework.
Some of the benefits are that you write less cloudformation code and you can locally debug/test your lambdas/step functions.
Here is my two cents on the best practice among your solutions:
While developing products, swagger or apiary are great tools to document your API and quickly mock the API before implementing them. With a mock API and documentation in the hands of (say) a product manager, it becomes easy to get started with a solid plan for development. But tools like swagger can auto-mock an API specification and if you wish to import this specification only to mock an API, then this import feature is a great tool to use, otherwise it is not. Let me explain why.
By importing an API and orchestrating AWS resources directly from swagger, you bring in lots of limitations, the primary one being your development process does not include a framework such as serverless or zappa. This would force us to directly write lambda functions using AWS console or AWS cli, and make the project architecture complicated.
In writing lambda functions without a framework, if we know upfront that our functions would be orthogonal to each other and do not share much common dependencies, then great, this would work, but for any project with (say) a database, functions accessing external API, some endpoints being guarded by an authorizer and having other resources, using a framework is definitely the better option. It is easier to create layers and common code, for example a database wrapper class.
When using any framework, it is better to start with the framework boilerplate and make the implementation to match the documentation. By studying the advantages and limitations of that framework, we can decide if it fits our architecture.
Also, IMO, this method is not widely used, and finding help might be tough later on as the project becomes more complex.
hope this helps.
Related
I am very interested in Integration Platform as a Service.
As we know, it is possible to generate an API spec from an API. Is the opposite possible?
I want to write a piece of software that automatically create some functions for calling the endpoints of an Open API. In order to achieve that, the piece of software should consume an API spec and generate the code. Theoretically, this could be possible, if the spec covers all endpoints with all parameters of the API, etc. but:
this is often not the case
specs are written differently from each other
My question is: what should my software consume in order to get reliable information about the API endpoints, parameters etc.? Is there a standard for that? Is the API spec the way to go?
Look at Github Copilot. They're able to generate pretty descent facsimiles of functions from API spec. Just a word of caution, the function might not be 100% accurate and so you'll still need to check over it.
In a properly designed webservice there are at least 4 layers, presentation, application, domain and infrastructure.
REST documentation describes only the presentation layer's outer surface: HTTP interface and operations, so it is not possible to generate a complete webservice based on the REST API documentation. If your application does not have any kind of logic, it is just a data structure and CRUD, then it is possible, but in that case you'd better to find a database which has a REST API and very good access control and problem solved mostly.
If you have some sort of standard documentation like WADL or JSON-LD with Hydra, then you can generate a REST API skeleton for the presentation. I just googled the topic a little bit, maybe this thesis can be useful for you: https://repositorio.ul.pt/bitstream/10451/35311/1/ulfc121800_tm_Telmo_Santos.pdf
Is it possible to produce/generate documentation using API Blueprint tool from Restful API code and If so how to use this tool any help?
If you are looking for a way how to generate a description of your API from the code then API Blueprint isn't probably the best choice as we believe it should represent the contract between everybody involved in the API design lifecycle. This is also the reason why we have built the testing tool – Dredd – https://github.com/apiaryio/dredd
With Dredd you can test your API implementation is matching to your blueprint. It wouldn't make much sense if the blueprint would be generated from the implementation.
Hope this does clarify.
The AWS documentation is seemingly endless, and different pages tell me different things. For example, one page tells me that AWSDynamoDBObjectMapper is the entry point to working with DynamoDB, while another tells me that AWSDynamoDB is the entry point to working with DynamoDB. Which class should I be using? Why?
EDIT: One user mentioned he didn't understand the question. To be more clear, I want to know, in general, what the difference is between using AWSDynamoDB and AWSDynamoDBObjectMapper as entry points to interfacing a DynamoDB.
Doc links for both:
AWSDynamoDB
AWSDynamoDBObjectMapper
Since both can clearly read, write, query, and scan, you need to pick out the differences. It appears to me that the ObjectMapper class supports the concept of mapping an AWSDynamoDBModel to a DB vs. directly manipulating specific objects (as AWSDynamoDB does). Moreover, it appears that AWSDynamoDB also supports methods for managing tables directly.
I would speculate that AWSDynamoDB is designed for managing data where the schema is pre-defined on the DB, and AWSDynamoDBObjectMapper is designed for managing data where the schema is defined by the client.
All of this speculation aside though, the most important bit you can glean from the documentation is:
Instead of making the requests to the low-level DynamoDB API directly from your application, we recommend that you use the AWS Software Development Kits (SDKs). The easy-to-use libraries in the AWS SDKs make it unnecessary to call the low-level DynamoDB API directly from your application. The libraries take care of request authentication, serialization, and connection management. For more information, go to Using the AWS SDKs with DynamoDB in the Amazon DynamoDB Developer Guide.
I would recommend this approach rather than worrying about the ambiguity of class documentation.
I'm having a hard time wrapping my mind around something and would appreciate some reading material on this concept.
I'm writing an application that relies heavily on providing API calls via a URI scheme. example.com/company/user/123123. The aspects of taking a URI string and converting it to an action makes sense.
But where I get confused is taking that process and utilizing within the MVC structure. Do I build calls using models or a library? My goal is to be able to do something like $this->company->user(12311), so that I can have the API functionality available externally and internally.
Also how do I make this functionality accessible without exposing core code?
One of the biggest problems with the word API is that it does not make a distinction between when you are making local in process calls and when you are making remote calls. This is the essence of the RPC style, using the same programmatic model regardless of where the code to be executed exists.
REST is explicitly about doing distributed computing and is optimized for those scenarios. Trying to use a RESTful interface as a local API is likely to produce something that is highly inefficient.
I would suggest not trying to use the same API internally and externally and I would go further and say try not to think of REST as a way of building APIs. REST is an approach to building distributed systems that requires consideration of the system holistically.
To address your question more specifically, I use an MVC approach to exposing Resources in my system. The Model is the Resource and the View is the Representation. The key to building a RESTful system is to identify the links between your models. These links are rendered into the respresentations as embedded links. Also, consider that your models should be more like Presentation Models than domain models as a RESTful interface is more about exposing the usage scenarios of a system than it is about exposing a domain model.
We are currently designing a REST API that we want to publish in a few months. Since this is a brand new application we can choose any other programming language other than PHP. At this moment we are using the following link to have a base of best practices for APIs.
What is the most suitable Rich Internet Application Programming Language to construct a REST API? I know you can accomplish this goal with almost any PL, we are looking for one that will give us the base. And while you are at it, if you can point the second better and the reasoning that will be perfect.
Thanks SO for this great website.
EDIT 1: Other link related to this question.
Depends on what your team is comfortable with.
You really can't go wrong with Ruby on Rails or Microsoft .NET (using WCF with REST endpoints).
Ruby on Rails is good if that architecture works for your application and you only need that REST endpoint.
With .NET, you can create the REST endpoint for your WCF service but also provide other endpoints if you find you need them.
I actually don't think you could use an RIA language to build a REST API, because a REST (Web) API is an collection of resources served via an HTTP server. An RIA usually runs client-side.
So I assume you're asking what's the most suitable programming language to build a REST API which will be used by an RIA.
There are many good choices. I'm not sure what your parameters are, so I'll suggest what I would use if I needed to build a REST API.
Some good choices:
Java, using the Restlet framework. I use this all the time and I'm very happy with it.
Ruby, using the Ruby on Rails framework or the Sinatra micro-framework
Python, using a micro-framework such as Bottle, djng, itty, juno, mnml, newf, web.py, or Werkzeug. It's definitely possible to use a full-blown framework such as Django or CherryPy, but I've found them to be not particularly well suited to this use case.
Hope this helps!
If not PHP, then Ruby or Python.